File Input
Basic usage
Model Value (showing file names):
<script setup lang="ts">
import { FileInput } from '@vuetags/inputs';
import { ref } from 'vue';
const model = ref<File[]>([]);
</script>
<template>
<p>
<file-input v-model="model" multiple />
Model Value (showing file names):
<ul>
<li v-for="file of model">{{ file.name }}</li>
</ul>
</p>
</template><script setup>
import { FileInput } from '@vuetags/inputs';
import { ref } from 'vue';
const model = ref([]);
</script>
<template>
<p>
<file-input v-model="model" multiple />
Model Value (showing file names):
<ul>
<li v-for="file of model">{{ file.name }}</li>
</ul>
</p>
</template>Model
You can use the v-model as you're used to in Vue. Check the official documentation for more information on how to use models.
WARNING
Note that the HTML file input does not allow setting files programmatically. So if you set the model from the parent, the input element will not show that files are selected. The model will have the files selected though.
Props
The FileInput element allows all default HTML properties and attributes. Apart from those the following properties are added:
validators
Validators are used to validate the user's input. Validation is triggered manually by using the validate function. These are either a single validator or an array of multiple validators. These can be predefined presets and/or custom functions.
Type definition
// One or more validation presets and/or custom functions
validators?: Validation | Validation[];
// Combination of presets and/or functions
type Validation = ValidationPreset | ValidationFunction;
// Available validation presets
type ValidationPreset = 'required';
// Validation function. Needs to return false or a string if validation fails,
// true otherwise
export type ValidationFunction<ModelValue = string> =
(modelValue: ModelValue, ...args: unknown[]) => boolean | string;A single validator
A single validator can be directly added to the prop. This can be done directly in the template or as a variable.
<script setup lang="ts">
import { FileInput } from '@vuetags/inputs';
</script>
<template>
<!-- A single preset -->
<file-input validators="required" />
<!-- A single function -->
<file-input :validators="(value: File[]) => value.length > 3" />
</template><script setup>
import { FileInput } from '@vuetags/inputs';
</script>
<template>
<!-- A single preset -->
<file-input validators="required" />
<!-- A single function -->
<file-input :validators="(value) => value.length > 3" />
</template>Multiple validators
Multiple validators can be added as an array. This can be a combination of custom functions and/or presets.
<script setup lang="ts">
import { FileInput } from '@vuetags/inputs';
const validatorFunction = (value: File[]) => value.length > 3;
</script>
<template>
<file-input :validators="['required', validatorFunction]" />
</template><script setup>
import { FileInput } from '@vuetags/inputs';
const validatorFunction = (value) => value.length > 3;
</script>
<template>
<file-input :validators="['required', validatorFunction]" />
</template>Available presets
required
The required preset checks if the checkbox is checked. If the checkbox is not checked, it will return 'required' in the validation result.
Emits
The FileInput element allows the default HTML events that are normally emitted.
Exposed functions
By utilizing Vue template refs you have access to additional functions. These can be programmatically triggered to perform the following actions.
focus
Programmatically trigger focus on the element.
<script setup lang="ts">
import { FileInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef<InstanceType<typeof FileInput>>('file-input');
function focus(): void {
element.value.focus();
}
</script>
<template>
<file-input ref="file-input" />
<button @click="focus">Trigger focus on element</button>
</template><script setup>
import { FileInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef('file-input');
function focus() {
element.value.focus();
}
</script>
<template>
<file-input ref="file-input" />
<button @click="focus">Trigger focus on element</button>
</template>blur
Programmatically remove focus from the element.
<script setup lang="ts">
import { FileInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef<InstanceType<typeof FileInput>>('file-input');
function blur(): void {
element.value.blur();
}
</script>
<template>
<file-input ref="file-input" />
<button @click="blur">Remove focus from element</button>
</template><script setup>
import { FileInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef('file-input');
function blur() {
element.value.blur();
}
</script>
<template>
<file-input ref="file-input" />
<button @click="blur">Remove focus from element</button>
</template>select
Programmatically trigger the file select interaction.
<script setup lang="ts">
import { FileInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef<InstanceType<typeof FileInput>>('file-input');
function select(): void {
element.value.select();
}
</script>
<template>
<file-input ref="file-input" />
<button @click="select">Trigger file select</button>
</template><script setup>
import { FileInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef('file-input');
function select() {
element.value.select();
}
</script>
<template>
<file-input ref="file-input" />
<button @click="select">Trigger file select</button>
</template>clear
Programmatically clear all selected files.
<script setup lang="ts">
import { FileInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef<InstanceType<typeof FileInput>>('file-input');
function clear(): void {
element.value.clear();
}
</script>
<template>
<file-input ref="file-input" />
<button @click="clear">Trigger file clear</button>
</template><script setup>
import { FileInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef('file-input');
function clear() {
element.value.clear();
}
</script>
<template>
<file-input ref="file-input" />
<button @click="clear">Trigger file clear</button>
</template>validate
Programmatically trigger validation of the current value. Runs all the provided validators in order in which they are provided and returns the results.
Return type definition
type ValidationResult = {
valid: boolean;
failed: string[];
};<script setup lang="ts">
import type { ValidationFunction } from '@vuetags/inputs';
import { FileInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef<InstanceType<typeof FileInput>>('file-input');
const validators: ValidationFunction[] = [
(value: File[]) => value.length > 0 || 'This field is required'
];
function validate(): void {
// If the value is empty, it logs:
// { valid: false, failed: ['This field is required'] }
console.log(element.value.validate());
}
</script>
<template>
<file-input ref="file-input" :validators="validators" />
<button @click="validate">Validate value</button>
</template><script setup>
import { FileInput } from '@vuetags/inputs';
import { useTemplateRef } from 'vue';
const element = useTemplateRef('file-input');
const validators = [
(value) => value.length > 0 || 'This field is required'
];
function validate() {
// If the value is empty, it logs:
// { valid: false, failed: ['This field is required'] }
console.log(element.value.validate());
}
</script>
<template>
<file-input ref="file-input" :validators="validators" />
<button @click="validate">Validate value</button>
</template>