FileElement ​

<FileElement :drop="true" ... />

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

<FileElement 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)

<FileElement default="image.jpeg" view="image" :clickable="true" ... />
<FileElement 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.

<!-- Relative path -->
<FileElement url="/images/" ... />

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

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

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

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

<FileElement :auto="true" ... />
<FileElement :auto="false" ... />

Whether files should automatically uploaded when they are selected.

Deprecated, use the followings instead:

• uploadTempFileEndpoint
• removeTempFileEndpoint
• removeFileEndpoint

<FileElement :urls="{ uploadTempFile: '...', removeTempFile: '...', removeFile: '...' }" ... />

The urls the file uploader should use for uploading and removing files.

uploadTempFile ​

• Request params:
  • file {File} - the selected file
  • formKey {string} - the form's formKey property
  • path {string} - the element's path using . syntax (eg. user.avatar)
  • ...params {any} - all params defined in params object
• Default: config.endpoints.uploadTempFile.url
• Returns: { tmp: TEMP_FILE_NAME, originalName: ORIGINAL_FILE_NAME }

Called when a file selected by the user should be temporarily uploaded.

removeTempFile ​

• Request params:
  • file {object} - the temporary uploaded file object (contains the response value of temp request)
  • formKey {string} - the form's formKey property
  • path {string} - the element's path using . syntax (eg. user.avatar)
  • ...params {any} - all params defined in params object
• Default: config.endpoints.removeTempFile.url
• Returns: void

Called when a temporarily uploaded file is removed if softRemove is false.

removeFile ​

• Request params:
  • file {string} - the uploaded file's name
  • formKey {string} - the form's formKey property
  • path {string} - the element's path using . syntax (eg. user.avatar)
  • ...params {any} - all params defined in params object
• Default: config.endpoints.removeFile.url
• Returns: void

Called when an uploaded file is removed if softRemove is false.

Deprecated, use the followings instead:

• uploadTempFileEndpoint
• removeTempFileEndpoint
• removeFileEndpoint

<FileElement :methods="{ temp: 'POST', removeTemp: 'DELETE', remove: 'DELETE' }" ... />

The methods should be used by urls. Defaults are:

• temp - config.endpoints.uploadTempFile.method
• removeTemp - config.endpoints.removeTempFile.method
• remove - config.endpoints.removeFile.method

<FileElement 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:

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

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

// vueform.config.js

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

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

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

<!-- Using a function to upload file -->
<FileElement :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:

<!-- Using a function to upload file without temp upload -->
<FileElement :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 endpoint can be disabled with false:

<!-- Using a function to upload file without temp upload -->
<FileElement :upload-temp-endpoint="false" ... />

More info in File Uploads guide.

<FileElement 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:

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

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

// vueform.config.js

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

<!-- Using a named endpoint -->
<FileElement 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:

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

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

More info in File Uploads guide.

<FileElement 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:

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

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

// vueform.config.js

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

<!-- Using a named endpoint -->
<FileElement 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:

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

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

More info in File Uploads guide.

<FileElement :params="{ extra_param: 'value' }" ... />

Params to be sent along with HTTP requests.

<FileElement :soft-remove="true" ... />

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

<FileElement name="element" ... />

Sets the element's name.

<FileElement id="field-id" ... />

Sets the id attribute of the file input (which is hidden).

<FileElement :disabled="true"... />
<FileElement :disabled="prop" ... /> <!-- computed / data (ref) prop -->
<FileElement :disabled="[['text', 'value']]" ... /> <!-- conditional -->
<FileElement :disabled="(el$, form$) => { return /* boolean */ }" ... />

Disables uploading a new file and removing an existing one.

If can be a boolean value.

It can be a computed / data (ref) prop.

It can be an array of conditions. When all conditions are met the element will become disabled.

It can be a function that receives the el$ element instance and form$ form instance params and expected to return a boolean.

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.

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

<FileElement label="Top" info="Top" info-position="top" ... />
<FileElement label="Right" info="Right" info-position="right" ... />
<FileElement label="Left" info="Left" info-position="left" ... />
<FileElement label="Bottom" info="Bottom" info-position="bottom" ... />

Sets the position of the info tooltip.

Can be also defined via #info slot.

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

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

Can be also defined via #description slot.

<FileElement before="Before" ... />

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

Can be also defined via #before slot.

<FileElement description="Description" between="Between" ... />

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

Can be also defined via #between slot.

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

<FileElement default="image.jpeg" ... />

Sets a default file.

<FileElement :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.

<FileElement :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.

<FileElement :submit="false" ... />

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

<FileElement rules="required|max:1024" ... />
<FileElement :rules="['required', 'max:1024']" ... />

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.

<FileElement field-name="Field name" rules="required" ... />

Sets the name of the field in validation rule messages.

<FileElement rules="required" :messages="{ required: 'Please select a 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.

<FileElement :display-errors="false" ... />

Whether element errors should be displayed.

<!-- field1 - type 'show' -->
<TextElement name="field1" ... />

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

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

<!-- image3.jpeg - only if field1 == 'show' -->
<FileElement 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.

<FileElement 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:

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

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

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 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 the rest. In case the label has full width (12) the file will also take up full space instead of becoming zero.

The value of wrapper defines the size of the file 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 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):

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

Note that while the size of the file 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:

<FileElement
  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 thedefault stings oflabelandwrapper`:

<FileElement 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:

<FileElement 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 cumn sizesan be defined globally in vueform.config.js or on form level using columns.

<FileElement :inline="true" ... />

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

<FileElement size="sm" ... />
<FileElement ... /> <!-- Default size: 'md' -->
<FileElement size="lg" ... />

The size of the element and its child components.

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

<FileElement :views="{
  ComponentName: 'alt'
}" ... />

The name of the views for the child components.

Learn more about views here.

<FileElement :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.:

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

Learn more about adding classes here.

<FileElement :add-class="{
  classname: 'class-value',
  classname: ['class-value'],
  classname: [{'class-value': true}],
}" ... />

Adds classes to any of FileElement 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.:

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

Learn more about adding classes here.

<FileElement :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.:

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

Learn more about removing classes here.

<FileElement :remove-class="{
  classname: ['class-value-1', 'class-value-2']
}" ... />

Removes classes from any of FileElement 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.:

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

Learn more about removing classes here.

<FileElement :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.:

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

Learn more about replacing classes here.

<FileElement :replace-class="{
  classname: {
    'from-class': 'to-class',
    'from-class': ['to-class'],
    'from-class': [{'to-class': true}],
  }
}" ... />

Replaces the classes of any class names of FileElement 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.:

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

Learn more about replacing classes here.

<FileElement :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.:

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

Learn more about overriding classes here.

<FileElement :override-classes="{
  ComponentName: {
    classname: 'class-value',
    classname: ['class-value'],
    classname: [{'class-value': true}],
  }
}" ... />

Overrides the classes of any of FileElement 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.:

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

Learn more about overriding classes here.

<template>
  <div id="app">
    <Vueform>
      <FileElement :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.

<FileElement :presets="['preset1', 'preset2']" ... />

The presets to be applied for the component.

Learn more about presets classes here.

<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: 'file',
          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.

The aria-* attributes of the input.

Whether the element is required (has required rule).

Whether the element should use a custom logic for checking if it is filled when validating.

Whether the element is filled is useCustomFilled is true.

Whether the element has its default value.

The stage the file is at:

• 0: file not selected
• 1: file selected
• 2: file temporarily uploaded
• 3: file permanently uploaded

The original or stored name of the file.

The clickable link of the uploaded file.

The preview of the file when view is image or gallery. Equals to the link if the file is already uploaded and base64 if only selected or temporarily uploaded.

The percentage of progress when the file is being temporarily uploaded (0-100).

Whether the file is permanently uploaded.

Whether the file uploader has any errors.

Whether async file removing request is in progress.

If the form is submitted and the file is not uploaded yet, the element will enter into preparing state and upload the temporary file before submitting the form.

Whether the file can be removed.

Whether temporary file can be uploaded.

Whether file can be selected.

The value of the element.

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.

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

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

Whether the element has no value filled in.

The path of the element using dot . syntax.

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

The parent component of the element.

Whether the element was already validated at least once.

Whether the element has any failing rules.

Whether the element's value was modified.

Whether the element has any async rules in progress.

Whether the element is pending, debouncing, uploading or removing.

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

All the errors of MessageBag.

The first error of MessageBag.

Whether no conditions are defined or they are all fulfilled.

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

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

Whether the element is disabled.

The ref to the outermost DOM of the element.

The main input field of the element.

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

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

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

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.

The component's template.

The component's classes.

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

The root form's component.

The element's component.

Whether the element has been already mounted.

Upload temporary file (async).

Removes file (async):

• in stage 1: sets the value to null
• in stage 2: submits a request to removeTemp endpoint (if softRemove: false) and sets the value to null
• in stage 3: submits a request to remove endpoint (if softRemove: false) and sets the value to null

Clears the manually added messages from the messageBag.

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.

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

Clears the element's value.

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

Disables the element.

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

Adds a listener for an event.

Removes all listeners for an event.

Fires and emits an event.

Checks each validation rule for the element (async). File element will only validate for min, max, between, size, mimetypes, mimes, dimensions, file, image, gt, gte, lt and lte rules and only before the temporary files are uploaded.

Removes the element's dirty state.

Sets the validators to default state.

Re-initializes validators when rules have changed.

Hides the element.

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

Triggered when the element's value is changed.

Triggered after the file is removed.

Triggered when temporary upload or file remove throws an error.

Triggered in beforeCreate hook.

Triggered in created hook.

Triggered in beforeMount hook.

Triggered in mounted hook.

Triggered in beforeUpdate hook.

Triggered in updated hook.

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

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

Renders a label for the element in ElementLabel 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.

Renders description for the element in ElementDescription component.

Renders an ElementText component before the file.

Renders an ElementText component after the file and before description.

Renders an ElementText component after the description and error.