MultifileElement

Renders a multi-file uploader.

Basic Usage

<MultifileElement> component can be used in a <Vueform> component:

vue
<template>
  <Vueform>
    <MultifileElement name="multifile" />
  </Vueform>
</template>

Configuration options can be passed over as regular component props. Check out Options section for available configuration options.

Options

Find below the list of options that can use to configure MultifileElement component. Options can be passed to the component via props in inline templates, or in the element's object when using schema.

drop

  • Type: boolean
  • Default: false
vue
<MultifileElement :drop="true" ... />

Whether DragAndDrop component should be used to select file(s) instead of a button.

sort

  • Type: boolean
  • Default: false
vue
<MultifileElement :sort="true" view="gallery" ... />

Whether the files can be sorted.

controls

  • Type: object
  • Default: {
    "add": true,
    "remove": true,
    "sort": true
    }
vue
<!-- Can't add --->
<MultifileElement :sort="true" :controls="{ add: false }" ... />

<!-- Can't remove --->
<MultifileElement :sort="true" :controls="{ remove: false }" ... />

<!-- Can't sort --->
<MultifileElement :sort="true" :controls="{ sort: false }" ... />

Defines the available controls. Object properties:

  • add - enables/disables adding a new file
  • remove - enables/disables removing files
  • sort - enables/disables sorting when sort is enabled

object

  • Type: boolean
  • Default: null
vue
<MultifileElement :object="false" ... />
<MultifileElement :object="true" ... />

Whether the file instances should be objects, where the file's value is contained in the storeFile object property (storeFile defaults to 'file').

When using storeOrder or fields options, instances will automatically have object: true.

storeFile

  • Type: string
  • Default: file
vue
<MultifileElement store-file="logo" ... />

The name of the object property that contains the file value when using object: true.

fields

  • Type: object
  • Default: {}
vue
<MultifileElement view="image" :fields="{
  label: { type: 'text', floating: 'File label' }
}"... />

Additional fields for each file instance. Can be any field type.

If fields is defined the MultifileElement's value will no longer be a plain array of file values. It will become an array of objects where the file's value is contained in the storeFile object property (storeFile defaults to 'file').

storeOrder

  • Type: string
  • Default: null
vue
<MultifileElement
  view="image"
  :sort="true"
  store-order="order"
  :fields="{
    order: { type: 'hidden' }
  }"
  :default="[
    { file: 'image.jpeg', order: 1 },
    { file: 'image2.jpeg', order: 2 },
    { file: 'image3.jpeg', order: 3 },
  ]"
... />

The name of the element that stores the order value when using sort. When storeOrder is defined object will be automatically set to true and the file's value will be contained in storeFile object-property.

The element that contains the store is recommended to be HiddenElement.

order

  • Type: string
  • Default: null
template
<!-- Using `object: false` --->
<MultifileElement order="asc" :object="false" @mounted="el$ => el$.load([
  'image3.jpeg',
  'image.jpeg',
  'image2.jpeg',
])" ... />

<!-- Using `object: true` and `orderBy` --->
<MultifileElement order="desc" order-by="order" :object="true" @mounted="el$ => el$.load([
  { file: 'image3.jpeg', order: 3 },
  { file: 'image.jpeg', order: 1 },
  { file: 'image2.jpeg', order: 2 },
])" ... />

Automatically sorts the files when data is loaded. Possible values: 'asc|desc'.

If object: false it will be sorted based on filenames (when uploaded files are loaded).

If object: true it should be used in conjunction with orderBy which defines the name of the object property that contains the order.

orderBy

  • Type: string
  • Default: null
vue
<MultifileElement order="asc" order-by="order" :object="true"
  @mounted="el$ => el$.load([
    { file: 'images/image3.jpeg', order: 3 },
    { file: 'images/image.jpeg', order: 1 },
    { file: 'images/image2.jpeg', order: 2 },
  ])
" ... />

The name of the object property that determines the order when using order. Defining this option automatically sets object to true and adds an a hidden element with the same name to fields if it is not defined yet.

file

  • Type: object
  • Default: {}
vue
<MultifileElement :file="{ rules: 'max:1024' }"... /> <!-- File max size: 1 MB -->

Additional options for each file instance that you would define for FileElement.

accept

  • Type: string|array
  • Default: null
vue
<MultifileElement accept=".jpg,.png,.gif" view="image" ... />

Resticts the accepted file types. To specify more than one value, separate the values with a comma (e.g. 'audio/*,video/*,image/*') or use an array (e.g. ['.jpg','.png','.gif']).

Possible values:

  • file_extension - specify the file extension(s) (e.g: .gif, .jpg, .png, .doc) the user can pick from
  • 'audio/*' - the user can pick all sound files
  • 'video/*' - the user can pick all video files
  • 'image/*' - the user can pick all image files
  • media_type - a valid media type, with no parameters (look at IANA Media Types for a complete list of standard media types)

clickable

  • Type: boolean
  • Default: true
vue
<MultifileElement :default="['image.jpeg']" view="image" :clickable="true" ... />
<MultifileElement :default="['image.jpeg']" view="image" :clickable="false" ... />

Whether the uploaded file should be clickable. If true the filename in the url will be prefixed with the value of the url option.

The file is only considered uploaded once its value is a string that contains the filename. Selected or temporarily uploaded files cannot be clicked.

url

  • Type: string|boolean
  • Default: /
vue
<!-- Relative path -->
<MultifileElement url="/images/" ... />

<!-- Different domain -->
<MultifileElement url="https://cdn.domain.com/images/" ... />

<!-- Turn off -->
<MultifileElement :url="false" ... />

The url prefix for clickable files. Set to false to disable url prefix.

previewUrl

  • Type: string
  • Default: undefined
vue
<MultifileElement preview-url="/images/previews/" ... />

The url prefix for uploaded image/gallery previews. If not defined the url will be used, unless url is set to false.

auto

  • Type: boolean
  • Default: true
vue
<MultifileElement :auto="false" ... />

Whether files should automatically uploaded when they are selected.

uploadTempEndpoint

  • Type: object|string|function
  • Default: config.endpoints.uploadTempFile
vue
<MultifileElement upload-temp-endpoint="/upload-file" ... />

The endpoint where files should be uploaded.

It can be a simple url like /upload-file but also an object containing url and method:

vue
<!-- Using an object as endpoint -->
<MultifileElement :upload-temp-endpoint="{
  url: '/files',
  method: 'POST'
}" ... />

It can be a named endpoint that references an endpoint in vueform.config.js:

js
// vueform.config.js

export default {
  endpoints: {
    upload_file: {
      url: '/files',
      method: 'POST'
    }
  }
}

vue
<!-- Using a named endpoint -->
<MultifileElement upload-temp-endpoint="upload_file" ... />

It can be an async function that handles the file upload and returns an object with data:

vue
<!-- Using a function to upload file -->
<MultifileElement :upload-temp-endpoint="async function(file, el$){
  let data = el$.form$.convertFormData({
    file,
  }) // befomes `FormData` object

  /* upload file */

  return {
    tmp: '...', // the temp file identifier
    originalName: '...', // the original name of the file that will be displayed to the user
  }
}" ... />

If the temporary uploading should be skipped the endpoint should return a string with the filename instead of an object. Eg:

vue
<!-- Using a function to upload file without temp upload -->
<MultifileElement :upload-temp-endpoint="async function(file, el$){
  let data = el$.form$.convertFormData({
    file,
  }) // befomes `FormData` object

  /* upload file */

  return 'filename.jpg'
}" ... />

If the file(s) should be sent with the all other form data upon submission (completely skipping temp uploading), the following callback can be used:

vue
<!-- Using a function to upload file without temp upload -->
<MultifileElement :upload-temp-endpoint="f => f" ... />

This will return the File object as it is instead of uploading thus keeping it as the element value, which will then get submitted with the form later on.

removeTempEndpoint

  • Type: object|string|function
  • Default: config.endpoints.removeTempFile
vue
<MultifileElement remove-temp-endpoint="/remove-temp-file" ... />

The endpoint where temp file remove requests should be submitted.

It can be a simple url like /remove-temp-file but also an object containing url and method:

vue
<!-- Using an object as endpoint -->
<MultifileElement :remove-temp-endpoint="{
  url: '/temp-files',
  method: 'DELETE'
}" ... />

It can be a named endpoint that references an endpoint in vueform.config.js:

js
// vueform.config.js

export default {
  endpoints: {
    remove_temp_file: {
      url: '/temp-files',
      method: 'DELETE'
    }
  }
}

vue
<!-- Using a named endpoint -->
<MultifileElement remove-temp-endpoint="remove_temp_file" ... />

It can be an async function that handles the remove and receives an object as first param containing tmp and originalName properties:

vue
<!-- Using a function to remove temp file -->
<MultifileElement :remove-temp-endpoint="async function(file, el$){
  const { tmp, originalName } = file

  /* remove temp file */
}" ... />

removeEndpoint

  • Type: object|string|function
  • Default: config.endpoints.removeFile
vue
<MultifileElement remove-endpoint="/remove-file" ... />

The endpoint where file remove requests should be submitted.

It can be a simple url like /remove-file but also an object containing url and method:

vue
<!-- Using an object as endpoint -->
<MultifileElement :remove-endpoint="{
  url: '/files',
  method: 'DELETE'
}" ... />

It can be a named endpoint that references an endpoint in vueform.config.js:

js
// vueform.config.js

export default {
  endpoints: {
    remove_file: {
      url: '/files',
      method: 'DELETE'
    }
  }
}

vue
<!-- Using a named endpoint -->
<MultifileElement remove-endpoint="remove_file" ... />

It can be an async function that handles the remove and receives the name of the uploaded file as first param:

vue
<!-- Using a function to remove file -->
<MultifileElement :remove-temp-endpoint="async function(file, el$){
  const filename = file // eg. background-image.png

  /* remove file */
}" ... />

params

  • Type: object
  • Default: {}
vue
<MultifileElement :params="{ extra_param: 'value' }" ... />

Params to be sent along with HTTP requests.

softRemove

  • Type: boolean
  • Default: false
vue
<MultifileElement :soft-remove="true" ... />

Whether removeTemp and remove endpoints should be called upon removing temp or uploaded file.

name

  • Type: string|number
  • Default: undefined
  • Required: true
vue
<MultifileElement name="element" ... />

Sets the element's name.

id

  • Type: string
  • Default: null
vue
<MultifileElement id="field-id" ... />

Sets the id attribute of the file list.

disabled

  • Type: boolean
  • Default: false
vue
<MultifileElement :disabled="true"... />

Disables uploading new files and removing/sorting existing ones.

label

  • Type: string|object|function
  • Default: null
  • Localizable: true

Sets a label for the element. Can be defined as a string, a Vue component object with a render function or as a function that receives el$ as its first a param.

Can also be defined via #label slot.

info

vue
<MultifileElement label="Info" info="Info" ... />

Renders an ElementInfo component next to the element's label. By default the icon shows the value of info when hovered, which can contain plain text or HTML. The element needs to have a label defined in order for info to be rendered.

Can be also defined via #info slot.

infoPosition

  • Type: string
  • Default: right
vue
<MultifileElement label="Top" info="Top" info-position="top" ... />
<MultifileElement label="Right" info="Right" info-position="right" ... />
<MultifileElement label="Left" info="Left" info-position="left" ... />
<MultifileElement label="Bottom" info="Bottom" info-position="bottom" ... />

Sets the position of the info tooltip.

Can be also defined via #info slot.

description

vue
<MultifileElement description="Lorem ipsum dolor sit amet" ... />

Renders the contents of description prop in the ElementDescription component below the file list. It can contain plain text or HTML.

Can be also defined via #description slot.

before

  • Type: object|string|number
  • Default: null
  • Localizable: true
vue
<MultifileElement before="Before" ... />

Renders the contents of before in a ElementText component before the file list. It can contain plain text or HTML.

Can be also defined via #before slot.

between

  • Type: object|string|number
  • Default: null
  • Localizable: true
vue
<MultifileElement description="Description" between="Between" ... />

Renders the contents of between in a ElementText component between the file list and the description. It can contain plain text or HTML.

Can be also defined via #between slot.

after

  • Type: object|string|number
  • Default: null
  • Localizable: true
vue
<MultifileElement description="Description" rules="required" after="After" ... />

Renders the contents of after in a ElementText component after the description and error. It can contain plain text or HTML.

Can be also defined via #after slot.

default

  • Type: array
  • Default: []
vue
<MultifileElement :default="['image.jpeg', 'image2.jpeg']" ... />

Sets a list of default files.

formatData

  • Type: function
  • Default: null
vue
<MultifileElement :format-data="(n, v) => ({[n]: /* transformed value */ })" ... />

Formats the element's requestData.

The first param is the element's name, the second is the value. The return value should be an object, which only contains one item with the element's name as key and the transformed value as value.

formatLoad

  • Type: function
  • Default: null
vue
<MultifileElement :format-load="(v) => /* transformed value */" ... />

Formats the data being loaded to the element when using load(data, format: true). It receives the value being loaded to the element as its first param and should return the formatted value of the element.

submit

  • Type: boolean
  • Default: true
vue
<MultifileElement :submit="false" ... />

If set to false the element's data will not be included in requestData and will not be submitted.

rules

  • Type: array|string|object
  • Default: null
vue
<MultifileElement rules="required|min:2" ... />
<MultifileElement :rules="['required', 'min:2']" ... />

The validation rules to be applied for the element.

The list of rules can be defined as a string separated by | or as an array, where each item should be a single validation rule.

To apply rules for each file, you can define rules in file option:

vue
<MultifileElement rules="required|max:2" :file="{ rules: 'max:1024' }" ... />

fieldName

  • Type: string
  • Default: name|label
vue
<MultifileElement field-name="Field name" rules="required" ... />

Sets the name of the field in validation rule messages.

messages

  • Type: object
  • Default: {}
vue
<MultifileElement rules="required" :messages="{ required: 'Please select at least one file' }" ... />

Overrides the default messages for the element's validation rules. The value is an object where each key is the name of a validation rule and the value is the error message that will be displayed when the rule fails.

You can override validation messages on form level with messages.

conditions

  • Type: array
  • Default: []
vue
<!-- field1 - type 'show' -->
<TextElement name="field1" ... />

<!-- image1.jpeg - only if field1 == 'show' -->
<MultifileElement :default="['image1.jpeg']" :conditions="[['field1', 'show']]" ... />

<!-- image2.jpeg - only if field1 != 'show' -->
<MultifileElement :default="['image2.jpeg']" :conditions="[['field1', '!=', 'show']]" ... />

<!-- image3.jpeg - only if field1 == 'show' -->
<MultifileElement :default="['image3.jpeg']" :conditions="[
  (form$, el$) => form$.el$('field1')?.value === 'show'
]" ... />

Shows or hides an element based on the provided conditions.

If an element's conditions are unmet the element will be hidden and its available property will become false. If hidden, its value will not be part of requestData.

Conditions can be provided as an array, where each item has to be either an array or a function. The element will only become available if all the conditions are fulfilled.

If a condition is provided as an array, the first value must be the path of an other field which value should be watched. The second is an operator that defines the type of comparison. The third is the expected value of the other field.

vue
<MultifileElement name="field" :conditions="[['other_field', '==', 'expected_value']]" ... />

Hint: In case you want to check for equality you might leave the operator and pass the expected value as the second param:

vue
<MultifileElement name="field" :conditions="[['other_field', 'expected_value']]" ... />

Available operators:

  • == - expect equality
  • != - expect inequality
  • > - expect the other element's value(s) to be higher
  • >=- expect the other element's value(s) to be higher or equal
  • < - expect the other element's value(s) to be lower
  • <= - expect the other element's value(s) to be lower or equal
  • ^ - expect the other element's value to start with
  • $ - expect the other element's value to end with
  • * - expect the other element's value to contain
  • in - expect to be among an array of values
  • not_in - expect not to be among an array of values
  • today - expect to be today
  • before - expect to be before a date (value can be a YYYY-MM-DD date string or today)
  • after - expect to be after a date (value can be a YYYY-MM-DD date string or today)

The expected value can also be defined as an array in which case any of its values will fulfill the condition.

Conditions can be defined with OR relation or as function. Learn more about conditions here.

columns

  • Type: object|string|number
  • Default: null
vue
<MultifileElement label="Label" :columns="{ container: 12, label: 3, wrapper: 12 }" ... />

Sets the size of the container, label and wrapper using the theme's grid system, where the:

  • container is the wrapper DOM that contains both label and wrapper
  • label contains the label
  • wrapper contains the file list.
container: 12
label: 3
wrapper: 12

The value of container defines the size of the element's container. 12 will result in full width, 6 in half, 4 in third and so on.

The value of label defines the amount of space the label should take up within the container. If the container is 12 and label is 6 the label is going to take up half the space and the file list will the other half (which is calculated automatically). If the container is 6 and label is 6, the label will only take up one forth and the file list the rest. In case the label has full width (12) the file list will also take up full space instead of becoming zero.

The value of wrapper defines the size of the file list wrapper within the space left for it in the container after subtracting the size of the label. If the container is 12 and label is 4 the space left for the file list is 8. In this case if the wrapper value is 12 it will take up the full space left for it (which is 8) while if it is changed to 6 it will only take up half the space left for it (4):

vue
<MultifileElement label="Label" :columns="{ container: 12, label: 4, wrapper: 12 }" ... />
<MultifileElement label="Label" :columns="{ container: 12, label: 4, wrapper: 6 }" ... />

Note that while the size of the file list wrapper changes, the size of extras like a description or error won't be limited to the wrapper's space. Instead it will take up the full space in the container left after subtracting the size of the label:

vue
<MultifileElement
  label="Label"
  :columns="{ container: 12, label: 4, wrapper: 6 }" 
  description="Lorem ipsum dolor sit amet, consectetur adipiscing elit"
... />

You can set the value of columns as a number in which case the container will receive its value without affecting the default settings of label and wrapper:

vue
<MultifileElement label="Label" :columns="6" ... /> <!-- { container: 6, label: 3, wrapper: 12 } -->

You can as well define column values for different breakpoints using the theme system's breakpoints like sm, md, etc. as keys:

vue
<MultifileElement label="Label" :columns="{
  xs: { container: 12, label: 12, wrapper: 12 },
  sm: { container: 12, label: 4, wrapper: 12 },
  md: 12,
  lg: { container: 12, label: 2, wrapper: 12 }
}" ... />

Default column sizes can be defined globally in vueform.config.js or on form level using columns.

inline

  • Type: boolean
  • Default: false
vue
<MultifileElement :inline="true" ... />

Renders the element and all of its components in a single <span> without applying columns.

size

  • Type: string
  • Default: undefined
vue
<MultifileElement size="sm" ... />
<MultifileElement ... /> <!-- Default size: 'md' -->
<MultifileElement size="lg" ... />

The size of the element and its child components.

view

  • Type: string
  • Default: file
vue
<MultifileElement view="alt" ... />

The name of the view to be used for the element and by default for its child components. If undefined the default view will be used. Child component views can be overridden with views option.

Views can be found at Views section.

Learn more about views here.

views

  • Type: object
  • Default: {}
vue
<MultifileElement :views="{
  ComponentName: 'alt'
}" ... />

The name of the views for the child components.

Learn more about views here.

addClasses

  • Type: object|function
  • Default: {}
vue
<MultifileElement :add-classes="{
  ComponentName: {
    classname: 'class-value',
    classname: ['class-value'],
    classname: [{'class-value': true}],
  }
}" ... />

Adds classes to any component's class names. The classes can have string or array values. When Vue style classes are used object values must be wrapped in an array.

Conditional classes can be passed as a function with form$ param, eg.:

vue
<MultifileElement :add-classes="(form$) => ({
  ComponentName: {
    classname: [
      { 'class-value': form$.el$('other_field')?.value === 'some_value' }
    ],
  }
})" ... />

Learn more about adding classes here.

addClass

  • Type: array|object|string|function
  • Default: null
vue
<MultifileElement :add-class="{
  classname: 'class-value',
  classname: ['class-value'],
  classname: [{'class-value': true}],
}" ... />

Adds classes to any of MultifileElement component's class names. Classes can have string or array values. When Vue style classes are used object values must be wrapped in an array.

Conditional classes can be passed as a function with form$ param, eg.:

vue
<MultifileElement :add-class="(form$) => ({
  classname: [
    { 'class-value': form$.el$('other_field')?.value === 'some_value' }
  ],
})" ... />

Learn more about adding classes here.

removeClasses

  • Type: object|function
  • Default: {}
vue
<MultifileElement :remove-classes="{
  ComponentName: {
    classname: ['class-value-1', 'class-value-2']
  }
}" ... />

Removes classes from any class names of any components. The classes to be removed must be listed in an array.

Conditional classes can be passed as a function with form$ param, eg.:

vue
<MultifileElement :remove-classes="(form$) => ({
  ComponentName: {
    classname: form$.el$('other_field')?.value === 'some_value'
      ? ['class-value-1', 'class-value-2']
      : [],
  }
})" ... />

Learn more about removing classes here.

removeClass

  • Type: array|object|function
  • Default: null
vue
<MultifileElement :remove-class="{
  classname: ['class-value-1', 'class-value-2']
}" ... />

Removes classes from any of MultifileElement component's class names. The classes to be removed must be listed in an array.

Conditional classes can be passed as a function with form$ param, eg.:

vue
<MultifileElement :remove-class="(form$) => ({
  classname: form$.el$('other_field')?.value === 'some_value'
    ? ['class-value-1', 'class-value-2']
    : [],
})" ... />

Learn more about removing classes here.

replaceClasses

  • Type: object|function
  • Default: {}
vue
<MultifileElement :replace-classes="{
  ComponentName: {
    classname: {
      'from-class': 'to-class',
      'from-class': ['to-class'],
      'from-class': [{'to-class': true}],
    }
  }
}" ... />

Replaces classes of any class names of any component. The keys are the original class names and the values are the replacements. The keys can only be single classes, while values can contain multiple ones in string or an array. When Vue style classes are used object values must be wrapped in an array.

Conditional classes can be passed as a function with form$ param, eg.:

vue
<MultifileElement :replace-classes="(form$) => ({
  ComponentName: {
    classname: form$.el$('other_field')?.value === 'some_value' ? {
      'from-class': 'to-class'
    } : {},
  }
})" ... />

Learn more about replacing classes here.

replaceClass

  • Type: object|function
  • Default: null
vue
<MultifileElement :replace-class="{
  classname: {
    'from-class': 'to-class',
    'from-class': ['to-class'],
    'from-class': [{'to-class': true}],
  }
}" ... />

Replaces the classes of any class names of MultifileElement component. The keys are the original class names and the values are the replacements. The keys can only be single classes, while values can contain multiple ones in string or an array. When Vue style classes are used object values must be wrapped in an array.

Conditional classes can be passed as a function with form$ param, eg.:

vue
<MultifileElement :replace-class="(form$) => ({
  classname: form$.el$('other_field')?.value === 'some_value' ? {
    'from-class': 'to-class'
  } : {},
})" ... />

Learn more about replacing classes here.

overrideClasses

  • Type: object|function
  • Default: {}
vue
<MultifileElement :override-classes="{
  ComponentName: {
    classname: 'class-value',
    classname: ['class-value'],
    classname: [{'class-value': true}],
  }
}" ... />

Overrides the classes of any component's class names. The classes can have string or array values. When Vue style classes are used object values must be wrapped in an array.

Conditional classes can be passed as a function with form$ param, eg.:

vue
<MultifileElement :override-classes="(form$) => ({
  ComponentName: form$.el$('other_field')?.value === 'some_value' ? {
    classname: 'class-value'
  } : {}
})" ... />

Learn more about overriding classes here.

overrideClass

  • Type: array|object|string|function
  • Default: null
vue
<MultifileElement :override-classes="{
  ComponentName: {
    classname: 'class-value',
    classname: ['class-value'],
    classname: [{'class-value': true}],
  }
}" ... />

Overrides the classes of any of MultifileElement component's class names. The classes can have string or array values. When Vue style classes are used object values must be wrapped in an array.

Conditional classes can be passed as a function with form$ param, eg.:

vue
<MultifileElement :override-class="(form$) => (form$.el$('other_field')?.value === 'some_value' ? {
  classname: 'class-value'
} : {})" ... />

Learn more about overriding classes here.

templates

  • Type: object
  • Default: {}
vue
<template>
  <div id="app">
    <Vueform>
      <MultifileElement :templates="{ ElementError }" ... />
    </Vueform>
  </div>
</template>

<script>
import { markRaw } from 'vue'
import CustomElementError from './CustomElementError.vue'

export default {
  data() {
    return {
      ElementError: markRaw(CustomElementError),
    }
  }
}
</script>

Overrides templates used by the component.

Learn more about overriding templates here.

presets

  • Type: array
  • Default: []
vue
<MultifileElement :presets="['preset1', 'preset2']" ... />

The presets to be applied for the component.

Learn more about presets classes here.

slots

  • Type: object
  • Default: {}
vue
<script>
import { Vueform, useVueform } from '@vueform/vueform';
import CustomDescriptionSlot from 'path/to/CustomDescriptionSlot.vue';

export default {
  mixins: [Vueform],
  setup: useVueform,
  data: () => ({
    vueform: {
      schema: {
        element: {
          type: 'multifile',
          slots: {
            label: '<span>Label</span>',
            description: CustomDescriptionSlot,
          }
        }
      }
    }
  })
}
</script>

With this option you can define slot values in a schema based form that you would normally just write inline. The value of a slot can be a plain string, HTML or a component with render function.

While this option can be also used in inline forms, it's primarily intended for schema based forms.

Properties

Properties include data, computed and inject properties of the component. You can use them by reaching the element's Vue component instance via form$'s el$(path) method or directly via this in options API or el$ in Composition API.

aria

  • Type: object
  • Group: computed

The aria-* attributes of the input.

hasUploading

  • Type: boolean
  • Group: computed

Whether any of the files are currently being uploaded to the server (initiated by the user).

preparing

  • Type: boolean
  • Group: computed

Whether any of the files are currently being uploaded to the server (initiated by form submit).

value

  • Type: any
  • Group: computed

The value of the element.

model

  • Type: any
  • Group: computed

Intermediary value between element's value and field's v-model. It is required when we need to transform the value format between the element and its field.

data

  • Type: object
  • Group: computed

The value of the element in {[name]: value} value format. This gets merged with the parent component's data.

requestData

  • Type: object
  • Group: computed

Same as data property except that it only includes the element's value if submit is not disabled and available is true (has no conditions or they are fulfilled).

empty

  • Type: boolean
  • Group: computed

Whether the element has no value filled in.

path

  • Type: string
  • Group: computed

The path of the element using dot . syntax.

dataPath

  • Type: string
  • Group: computed

The path of the element's data using dot . syntax.

children$

  • Type: object
  • Group: computed

Child element components.

hasAdd

  • Type: boolean
  • Group: computed

Whether adding new files is allowed. Will return false if the element has isDisabled: true. Can be disabled manually by setting controls.add to false.

hasRemove

  • Type: boolean
  • Group: computed

Whether remove files is allowed. Will return false if the element has isDisabled: true or a temporary file upload is in progress. Can be disabled manually by setting controls.remove to false.

hasSort

  • Type: boolean
  • Group: computed

Whether list files should be sortable. Can be enabled by setting sort to true, but will return false if the element has isDisabled: true or a temporary file upload is in progress.

sorting

  • Type: boolean
  • Group: data

Whether the list is currently being sorted (an item is dragged).

isSortable

  • Type: boolean
  • Group: computed

Whether the list is sortable. Can be enabled with sort option, but it will disabled if isDisabled is true.

orderByName

  • Type: string
  • Group: computed

The name of the field (when using fields) by which the files should be ordered.

validated

  • Type: boolean
  • Group: computed

Whether the element and all of its children was already validated at least once.

invalid

  • Type: boolean
  • Group: computed

Whether the element or any of its children has any failing rules.

dirty

  • Type: boolean
  • Group: computed

Whether the element's or any of its children's value was modified.

pending

  • Type: boolean
  • Group: computed

Whether the element or any of its children has any async rules in progress.

debouncing

  • Type: boolean
  • Group: computed

Whether the element or any of its children have a validation rule with pending debounce.

busy

  • Type: boolean
  • Group: computed

Whether the element or any of its children is pending or debouncing.

messageBag

  • Type: MessageBag
  • Default: MessageBag
  • Group: data

Instance of MessageBag service. Custom errors and messages can be added.

errors

  • Type: array
  • Group: computed

All the errors of MessageBag.

error

  • Type: string
  • Group: computed

The first error of MessageBag.

available

  • Type: boolean
  • Group: computed

Whether no conditions are defined or they are all fulfilled.

hidden

  • Type: boolean
  • Default: false
  • Group: data

Whether the element was hidden programmatically with show() or hide() methods.

visible

  • Type: boolean
  • Group: computed

Whether the element is visible. It's false when available or active is false or hidden is true.

isDisabled

  • Type: boolean
  • Group: computed

Whether the element is disabled.

container

  • Type: HTMLElement
  • Group: data

The ref to the outermost DOM of the element.

input

  • Type: HTMLElement
  • Group: data

The main input field of the element.

fieldId

  • Type: string
  • Group: computed

The id of the file list. If id is not provided path will be used.

hasLabel

  • Type: boolean
  • Group: computed

Whether the element has a label option, a #label slot or Vueform component's forceLabels option is true.

Size

  • Type: string
  • Group: computed

The resolved size of the element and all of its child components.

View

  • Type: string
  • Group: computed

The name of the resolved view for the component and the default view for its child components. Child component views can be overridden with views option. This one should be used to determine the component's view in class functions.

template

  • Type: object
  • Group: computed

The component's template.

classes

  • Type: object
  • Group: computed

The component's classes.

theme

  • Type: object
  • Group: inject

The global theme object, which contains all the default templates and classes.

form$

  • Type: Vueform
  • Group: inject

The root form's component.

el$

  • Type: VueformElement
  • Group: computed

The element's component.

mounted

  • Type: boolean
  • Default: true
  • Group: data

Whether the element has been already mounted.

Methods

The methods of the component that you can use by reaching the element's Vue component instance via form$'s el$(path) method or directly via this in options API or el$ in Composition API.

add

  • Arguments:
    • {any} value* - value of the appended element (optional)
  • Returns: number

Appends a new item.

remove

  • Arguments:
    • {number} index* - index of items to be removed
  • Returns: void

Removes an items by its index.

clearMessages

  • Returns: void

Clears the manually added messages from the messageBag.

load

  • Arguments:
    • {any} value* - the value to be loaded
    • {boolean} format* - whether the loaded value should be formatted with formatLoad before setting the value of the element (default: false)
  • Returns: void

Loads value to the element using optional formatLoad formatter. This is the method that gets called for each element when loading data to the form with format: true.

update

  • Arguments:
    • {any} value* - the value to be set
  • Returns: void

Updates the value of the element similarly to load, only that it can't format data.

clear

  • Returns: void

Clears the element's value.

reset

  • Returns: void

Resets the element's value to default (or empty if default is not provided). Also resets all the validation state for the element.

disable

  • Returns: void

Disables the element.

enable

  • Returns: void

Enables the element even if it is disabled by disabled option.

on

  • Arguments:
    • {string} event* - name of the event to listen for
    • {function} callback* - callback to run when the event is triggered
  • Returns: void

Adds a listener for an event.

off

  • Arguments:
    • {string} event* - name of the event to remove
  • Returns: void

Removes all listeners for an event.

fire

  • Arguments:
    • {any} args* - list of arguments to pass over to the event callback
  • Returns: void

Fires and emits an event.

validate

  • Returns: Promise

Checks each validation rule for the element and validates children (async).

validateValidators

  • Returns: Promise

Checks each validation rule for the element (async).

validateChildren

  • Returns: Promise

Validates every child (async).

clean

  • Returns: void

Removes the element's dirty state.

resetValidators

  • Returns: void

Sets the validators to default state.

reinitValidation

  • Returns: void

Re-initializes validators when rules have changed.

hide

  • Returns: void

Hides the element.

show

  • Returns: void

Shows the element if it was hidden with hide() method.

Events

With events you can subscribe to different events broadcasted by the element. It can be used inline as regular Vue event listeners with @event format. In schema it can be used in PascalCase format prefixed with on (eg. onChange).

vue
<template>
  <Vueform>
    <MultifileElement @{eventName}="handler" ... />
  </Vueform>
</template>
vue
<script>
import { Vueform, useVueform } from '@vueform/vueform'

export default {
  mixins: [Vueform],
  setup: useVueform,
  data: () => ({
    vueform: {
      schema: {
        element: {
          type: 'multifile',
          on{EventName}() {
            // ...
          }
        }
      }
    }
  })
}
</script>

You can also use on(event, callback) method to subscribe to events.

change

  • Params:
    • {string} newValue - the new value
    • {string} oldValue - the old value
    • {component} el$ - the element's component

Triggered when the element's value is changed.

add

  • Params:
    • {number} index - the index of the added item
    • {File|object|string} addedValue - the added value
    • {array} value - the element's value after the item is added

Triggered when a new item is added to the list.

remove

  • Params:
    • {number} index - the index of the removed item
    • {array} value - the element's value after the item is removed

Triggered when a new item is removed from the list.

sort

  • Params:
    • {array} value - the element's value after sorting
    • {number} oldIndex - the old index of the moved element
    • {number} newIndex - the new index of the moved element
    • {component} el$ - the moved element's component

Triggered when items are being sorted by the user, when sort: true.

beforeCreate

  • Params:
    • {component} el$ - the element's component

Triggered in beforeCreate hook.

created

  • Params:
    • {component} el$ - the element's component

Triggered in created hook.

beforeMount

  • Params:
    • {component} el$ - the element's component

Triggered in beforeMount hook.

mounted

  • Params:
    • {component} el$ - the element's component

Triggered in mounted hook.

beforeUpdate

  • Params:
    • {component} el$ - the element's component

Triggered in beforeUpdate hook.

updated

  • Params:
    • {component} el$ - the element's component

Triggered in updated hook.

beforeUnmount

  • Params:
    • {component} el$ - the element's component

Triggered in beforeUnmount (or beforeDestroy in Vue 2) hook.

unmounted

  • Params:
    • {component} el$ - the element's component

Triggered in unmounted (or destroyed in Vue 2) hook.

Views

Alternative views for the component that can be used with view option.

default

vue
<MultifileElement name="multifile" />

image

vue
<MultifileElement name="multifile" view="image" />
vue
<MultifileElement name="multifile" view="gallery" />

Slots

Slots can be used inline or in slots option object when used in schema:

vue
<template>
  <Vueform>
    <MultifileElement ... >
      <template #{slot-name}="scope">
        <!-- ... --->
      </template>
    </MultifileElement>
  </Vueform>
</template>
vue
<script>
import { Vueform, useVueform } from '@vueform/vueform'

export default {
  mixins: [Vueform],
  setup: useVueform,
  data: () => ({
    vueform: {
      schema: {
        element: {
          type: 'multifile',
          slots: {
            {slotName}: // implementation
          }
        }
      }
    }
  })
}
</script>

label

  • Scope:
    • {component} el$ - the element's component

Renders a label for the element in ElementLabel component.

info

  • Scope:
    • {component} el$ - the element's component

Renders an info icon in ElementInfo component next the the element label. When the icon is hovered it shows the content of this slot. The element needs to have a label to render this.

description

  • Scope:
    • {component} el$ - the element's component

Renders description for the element in ElementDescription component.

before

  • Scope:
    • {component} el$ - the element's component

Renders an ElementText component before the file list.

between

  • Scope:
    • {component} el$ - the element's component

Renders an ElementText component after the file list and before description.

after

  • Scope:
    • {component} el$ - the element's component

Renders an ElementText component after the description and error.

👋 Hire Vueform team for form customizations and developmentLearn more