Vueform

Renders the form.

Basic Usage

<Vueform> component can be used globally and serves as a container for elements and form components:

vue
<template>
  <Vueform size="lg">
    <StaticElement name="head">
      <h3>Login</h3>
    </StaticElement>
    <TextElement
      name="email"
      placeholder="Email"
      default="john@doe.com"
    />
    <TextElement
      name="password"
      input-type="password"
      placeholder="Password"
      default="********"
    />
    <ButtonElement name="submit" submits>
      Submit
    </ButtonElement>
  </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 Vueform component. Options can be passed to the component via props.

schema

  • Type: object
vue
<Vueform :schema="{
  name: {
    type: 'text',
    label: 'Name',
    placeholder: 'Your name'
  },
  email: {
    type: 'text',
    label: 'Email',
    placeholder: 'Your work email'
  },
}" ... />

This option can be used to define form elements in an object instead of inline templates. This method also allows storing form elements in JSON objects that can be stored in databases.

The object keys are the names of the elements while the values define the element options (same as props in inline templates).

Elements defined in schema will be rendered in FormElements component within the form which serves as a wrapper.

tabs

  • Type: object
vue
<Vueform
  :tabs="{
    profile: {
      label: 'Profile',
      elements: ['name', 'email', 'bio'],
    },
    gallery: {
      label: 'Gallery',
      elements: ['images'],
    },
  }"
  :schema="{
    name: { ... },
    email: { ... },
    bio: { ... },
    images: { ... },
  }"
/>

Similarly to schema and steps this option can be used to define form tabs in an object instead of inline templates.

The object keys are the name of the tabs while the values contain the tab options (same as props in inline templates).

Tabs are rendered in FormTabs component with a FormTab component for each.

steps

  • Type: object
vue
<Vueform
  :steps="{
    profile: {
      label: 'Profile',
      elements: ['name', 'bio'],
    },
    contact: {
      label: 'Contact',
      elements: ['email', 'phone'],
    },
    gallery: {
      label: 'Gallery',
      elements: ['images'],
    },
  }"
  :schema="{
    name: { ... },
    bio: { ... },
    email: { ... },
    phone: { ... },
    images: { ... },
  }"
/>

Similarly to schema and steps this option can be used to define form steps in an object instead of inline templates.

The object keys are the name of the steps while the values contain the step options (same as props in inline templates).

Steps are rendered in FormSteps component with a FormStep component for each.

stepsControls

  • Type: boolean
  • Default: true
vue
<Vueform :steps-controls="false" ... />

Whether FormStepsControls component should be displayed when steps are defined.

scrollOnNext

  • Type: boolean
vue
<Vueform :scroll-on-next="false" ... />

Whether to scroll to the top of the form on hitting Next button when using steps.

Can also be set on config level.

validateOn

  • Type: string
vue
<Vueform validate-on="change|step" ... />

Determines when the form should trigger validation. Values must be concatenated with |. Possible values: change and step.

If change is present, an element will be validated when its value is changed.

If step is present, all the elements within a step will be validated when the user tries to navigate to the next step using the Next form step control.

The form always validates unvalidated elements before submitting data to the server.

scrollToInvalid

  • Type: boolean
vue
<Vueform :scroll-to-invalid="false" ... />

Whether to scroll to the first invalid element when the form gets submitted.

Can also be set on config level.

showRequired

  • Type: array
vue
<Vueform rules="required" :show-required="['label', 'placeholder', 'floating']" ... />

The list of element assets where an asterix * should be shown if the element has required validation rule. The possible items are label, placeholder and floating.

Can also be set on config level.

displayErrors

  • Type: boolean
vue
<Vueform :display-errors="false" ... />

Whether error messages from messageBag should be displayed above the form in FormErrors component.

displayMessages

  • Type: boolean
vue
<Vueform :display-errors="false" ... />

Whether messages from messageBag should be displayed above the form in FormMessages component.

messages

  • Type: object
vue
<Vueform :messages="{ required: 'Please fill in' }" ... />

Overrides the default messages for each elements' validation rules within the form. The value is an object where each key is a 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 element level with messages.

endpoint

  • Type: string|boolean|function|promise
vue
<Vueform endpoint="/user/create" ... />

The endpoint where the form should be submitted on submit().

It can also be a named endpoint, referencing an endpoint in vueform.config.js:

js
// vueform.config.js

export default {
  endpoints: {
    create_user: {
      url: '/users',
      method: 'post'
    }
  }
}

vue
<!-- Using a named endpoint -->
<Vueform endpoint="create_user" ... />

If set to false submitting to endpoint will be disabled and it can be handled manually on @submit event:

vue
<!-- Disabling endpoint -->
<Vueform :endpoint="false" ... />

Alternatively, it can be an async function that receives formData and form$ params and handles the submit:

vue
<!-- Using a function to upload file -->
<Vueform :endpoint="async function(FormData, form$){
  const formData = FormData // FormData instance
  const data = form$.data // form data including conditional data
  const requestData = form$.requestData // form data excluding conditional data

  // handle form submission
}" ... />

method

  • Type: string
vue
<Vueform method="POST" ... />

The request method that should be used to send data on submit().

prepare

  • Type: function
vue
<Vueform :prepare="async (form$) => {
  try {
    // async request
  } catch (error) {
    throw error // cancels form submit
  }
}" ... />

An async function that is called before data is submitted to the server. It receives form$ as its form param which is the Vue component instance of the form. It can cancel the submit process by throwing an error.

formKey

  • Type: string|number
vue
<Vueform form-key="nE8e4wY5mcn5q1nTNakf" ... />

A unique key that is sent to the backend along with form data on submit(). Its primary purpose is to help identify a form if you are using a single endpoint to process all your forms.

formData

  • Type: function
vue
<Vueform :form-data="form$ => form$.convertFormData(form$.requestData)"... />

This function can be used to choose which one of the form's data set should be sent to the server on submit(). The form has two different objects that contain form data:

  • data - contains the full form data, including data from elements which conditions aren't met or submit is disabled for them
  • requestData - contains only form data from elements which conditions are met and submit is not disabled for them (this is the default).

The function receives a form$ prop, which is the Vue component instance of the form and expects to return the form data that should be submitted to the server on submit().

The convertFormData() method converts the data object to FormData. This might be left out if you don't want to send multipart/form-data request.

value

  • Type: object
vue
<Vueform v-model="data" ... /> <!-- same as :value="data" @input="data = $event.target.value" -->

This property allows you to store the form data in an external object (similarly to regular inputs) and used by v-model Vue 2.

The v-model directive does two things in Vue 2:

  • assigns :value prop to the component
  • listens to the @input event of the component and updates the value when emitted.

If you want to use it, you either have to define a v-model or :value prop and listening to @input event as well.

By default the form stores its data internally so you don't have to provide :value or v-model, unless you want to.

IMPORTANT: contrary to regular v-model, two-way data binding is optional in Vueform and have to be manually enabled using sync option.

modelValue

  • Type: object
vue
<Vueform v-model="data" ... /> <!-- same as :model-value="data" @update:model-value="data = $event" -->

The same as value option except that modelValue should be used with @update:model-value event instead of value & @input in Vue 3.

sync

  • Type: boolean
vue
<Vueform v-model="data" :sync="true" ... />

Two-way data binding is optional in Vueform and can be enabled with this option.

When sync: true the v-model object will be updated when the form data is changed (eg. by user input) and direct changes made to the object outside of Vueform will also be reflected in the form.

If sync: false the v-model object will be still updated when the form data is changed (eg. by user input) but direct changes made to it outside of Vueform will not be reflected in the form.

When using a lot elements or deeply nested elements the performance can be affected if sync is enabled. Make sure to only use sync if you actually need two-way data binding.

default

  • Type: object
template
<Vueform :default="{ name: 'John Doe', email: 'john@doe.com' }" ...>
  <TextElement name="name" />
  <TextElement name="email" />
</Vueform>

Sets the default data for the form.

forceNumbers

  • Type: boolean
html
<!-- Form `data` & `requestData` will be string -->
<Vueform>
  <TextElement default="123" />
  <TextElement default="123.456" />
  <TextElement default="123,456" />
</Vueform>

<!-- Form `data` & `requestData` will be number -->
<Vueform force-numbers>
  <TextElement default="123" />
  <TextElement default="123.456" />
  <TextElement default="123,456" />
  <TextElement default="123a" />
</Vueform>

Whether text input values should be transformed to a number in form data and requestData. If the input value contains any non-numeric character (except for . and ,) it will be kept as string.

It can be also set on element level or config level.

formatData

  • Type: function
vue
<Vueform :format-data="(requestData) => ({ /* transformed value */ })" ... />

Formats the form's requestData before submitting it to the server.

It receives the original requestData as its first param and expects to have a return with converted/transformed form data.

This value will only be used when the form is submitted and it does not affect the form's actual data.

formatLoad

  • Type: function
vue
<Vueform :format-load="(data) => /* transformed value */" ... />

Formats the data being loaded to the form with load(data, format: true). It receives data as its first param which is the original data being loaded. It expects to return a transformed/converted data that will be loaded to elements.

loading

  • Type: boolean
vue
<Vueform :loading="true" ... />

Manually triggers the loading state of the form. When the form is in loading state it cannot be submitted and submit button will display a loader while becoming disabled.

disabled

  • Type: boolean|function|object|array
vue
<Vueform :disabled="true" ... />
<VueformElement :disabled="prop" ... /> <!-- computed / data (ref) prop -->
<VueformElement :disabled="[['text', 'value']]" ... /> <!-- conditional -->
<VueformElement :disabled="(form$) => { return /* boolean */ }" ... />

Prevents the form from being submitted.

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 form submission will be disabled.

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

columns

  • Type: object
template
<Vueform :columns="{ container: 12, label: 3, wrapper: 12 }" ...>
  <TextElement label="Label" ... />
</Vueform>

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

  • container is the outermost DOM that contains both label and wrapper
  • label contains the label
  • wrapper contains the element.
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 element's wrapper 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 element's wrapper the rest. In case the label has full width (12) the element's wrapper will also take up full space instead of becoming zero.

The value of wrapper defines the size of the element's 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 element's wrapper is 8. In this case if the wrapper value is 12 it will take up the full space left for the it (which is 8) while if it is changed to 6 it will only take up half the space left for it (4):

template
<Vueform :columns="{ container: 12, label: 4, wrapper: 12 }" ...>
  <TextElement label="Label" ... />
</Vueform>

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

Note that while the size of the element's wrapper container changes the size of other 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:

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

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

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

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

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

Column sizes can be defined globally in vueform.config.js or uniquely for each element using the element's columns option.

forceLabels

  • Type: boolean
vue
<Vueform :force-labels="true" />

Whether empty labels should be displayed for elements.

floatPlaceholders

  • Type: boolean
vue
<Vueform :float-placeholders="true" />

Whether floating labels should be automatically created from placeholders (unless they are explicitly defined).

size

  • Type: string
template
<Vueform size="sm">
  <TextElement ... />
  <TextareaElement ... />
</Vueform>

The default size of the elements.

view

  • Type: string
vue
<Vueform view="alt" ... />

The name of the view to be used for the component. If undefined the default view will be used. Child component default views can be set with views option.

Learn more about views here.

views

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

The name of the default views for the child components.

Learn more about views here.

addClasses

  • Type: object|function
vue
<Vueform :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
<Vueform :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
vue
<Vueform :add-class="{
  classname: 'class-value',
  classname: ['class-value'],
  classname: [{'class-value': true}],
}" ... />

Adds classes to any of Vueform 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
<Vueform :add-class="(form$) => ({
  classname: [
    { 'class-value': form$.el$('other_field')?.value === 'some_value' }
  ],
})" ... />

Learn more about adding classes here.

removeClasses

  • Type: object|function
vue
<Vueform :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
<Vueform :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
vue
<Vueform :remove-class="{
  classname: ['class-value-1', 'class-value-2']
}" ... />

Removes classes from any of Vueform 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
<Vueform :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
vue
<Vueform :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
<Vueform :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
vue
<VueformElement :replace-class="{
  classname: {
    'from-class': 'to-class',
    'from-class': ['to-class'],
    'from-class': [{'to-class': true}],
  }
}" ... />

Replaces the classes of any class names of Vueform 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
<Vueform :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
vue
<Vueform :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
<Vueform :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
vue
<Vueform :override-classes="{
  ComponentName: {
    classname: 'class-value',
    classname: ['class-value'],
    classname: [{'class-value': true}],
  }
}" ... />

Overrides the classes of any of Vueform 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
<Vueform :override-class="(form$) => (form$.el$('other_field')?.value === 'some_value' ? {
  classname: 'class-value'
} : {})" ... />

Learn more about overriding classes here.

templates

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

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

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

Overrides the default templates used within the form.

Learn more about overriding templates here.

presets

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

The presets to be applied on a form level.

Learn more about presets classes here.

multilingual

  • Type: boolean
template
<Vueform :multilingual="true" ...>
  <TTextElement name="title" placeholder="Title">
</Vueform>

Whether a language selector for multilingual elements (eg. TTextElement or TTextareaElement) should be displayed above the form.

languages

  • Type: object
vue
<Vueform :languages="{
  en: 'English',
  zh: 'Chinese',
}" />

The object of available languages when using multilingual: true. If not defined and multilingual is used the default languages will be used from vueform.config.js.

language

  • Type: string
vue
<Vueform language="zh" ... />

The default language that should be selected when using multilingual: true.

locale

  • Type: string
vue
<Vueform locale="zh" ... />

Overrides the global locale for this form only.

providers

  • Type: object

useProviders

  • Type: object

providerOptions

  • Type: object

Properties

All the data, computed and inject properties of the component.

validation

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

Enables/disables validation for the form globally.

conditions

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

Enables/disables conditions for the form globally.

selectedLanguage

  • Type: string
  • Default: config.language
  • Group: data

The code of the currently selected language (eg. en).

submitting

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

Whether the async process of submitting the form is currently in progress.

cancelToken

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

The axios cancel token when a request is in progress.

formErrors

  • Type: array
  • Group: computed

Form errors including element errors and the ones added to messageBag manually.

formMessages

  • Type: array
  • Group: computed

Form messages including element messages and the ones added to messageBag manually.

hasTabs

  • Type: boolean
  • Group: computed

Whether the form has any tabs.

hasErrors

  • Type: boolean
  • Group: computed

Whether the form has any errors.

hasMessages

  • Type: boolean
  • Group: computed

Whether the form has any messages.

isMultilingual

  • Type: boolean
  • Group: computed

Whether the form is multilingual and should show FormLanguages component. Returns true if multilingual is enabled.

showErrors

  • Type: boolean
  • Group: computed

Whether the form should display errors above the form with FormErrors component. Can be disabled by displayErrors or in config.displayErrors.

showMessages

  • Type: boolean
  • Group: computed

Whether the form should display messages above the form with FormMessages component. Can be disabled by displayMessages or in config.displayMessages.

showLanguages

  • Type: boolean
  • Group: computed

Whether the form should show langauge selectors.

showSteps

  • Type: boolean
  • Group: computed

Whether the form should show FormSteps component. Returns true if steps has value.

showTabs

  • Type: boolean
  • Group: computed

Whether the form should show FormTabs component. Returns true if tabs has value.

showStepsControls

  • Type: boolean
  • Group: computed

Whether the form should display steps controls below form with FormStepsControls component when it has steps. Can be disabled with stepsControls.

extendedTheme

  • Type: object
  • Group: computed

The selected theme, extended by local template and class overrides, using templates, addClasses and replaceClasses.

tree

  • Type: array
  • Group: computed

The tree representation of the form schema.

flatTree

  • Type: array
  • Group: computed

The flat tree representation of the form schema.

translations

  • Type: object
  • Group: computed

The translation tags of the current locale.

locale$

  • Type: string
  • Group: computed

The active locale of the form.

steps$

  • Type: FormSteps
  • Group: data

The FormSteps component.

tabs$

  • Type: FormTabs
  • Group: data

The FormTabs component.

preparing

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

Whether the async process of preparing the elements for submit is currently in progress.

data

  • Type: object
  • Group: computed

The form data including the data of all elements even the ones with available: false and submit: false.

requestData

  • Type: object
  • Group: computed

The form data excluding elements with available: false and submit: false. This one gets submitted by default, but can be changed with formData

validated

  • Type: boolean
  • Group: computed

Whether each element in the form has been validated at least once.

invalid

  • Type: boolean
  • Group: computed

Whether the form has any invalid elements.

dirty

  • Type: boolean
  • Group: computed

Whether the form has any elements which were modified.

pending

  • Type: boolean
  • Group: computed

Whether the form has any elements with pending async validation.

debouncing

  • Type: boolean
  • Group: computed

Whether the form has any elements with active debounce process.

busy

  • Type: boolean
  • Group: computed

Whether the form has any elements with busy: true or the isLoading, preparing or submitting property is true.

messageBag

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

Instance of MessageBag service. It can be used to add custom errors and messages.

isDisabled

  • Type: boolean
  • Group: computed

Whether submitting the form is disabled. Returns true if:\n* the form has any invalid elements and validateOn contains change\n* the form is busy\n* manually disabled with disabled option.

isLoading

  • Type: boolean
  • Group: computed

Whether loading state is triggered manually via loading option.

Size

  • Type: string
  • Group: computed

The resolved default size for each element and component within the form.

View

  • Type: string
  • Group: computed

The name of the resolved view for Vueform component. 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.

form$

  • Type: Vueform
  • Group: computed

The form component instance (self).

Methods

The methods of the component.

clearMessages

  • Returns: void

Clears the manually added messages from the form's and each element's messageBag.

convertFormData

  • Arguments:
    • {object} data* - the data to be converted
  • Returns: FormData

Converts form data to FormData.

send

  • Returns: Promise

Sends form data to endpoint with the selected method (async).

cancel

  • Returns: void

Cancels the form request in progress.

disableValidation

  • Returns: void

Disabled form validation globally.

enableValidation

  • Returns: void

Enables form validation globally.

enableConditions

  • Returns: void

Enables conditions globally.

disableConditions

  • Returns: void

Disables conditions globally.

setLanguage

  • Arguments:
    • {string} code* - the language code to be selected
  • Returns: void

Sets current language when using multilingual.

handleSubmit

  • Returns: void

Handles submit event.

el$

  • Arguments:
    • {string} path* - path of the element
    • {object} elements - the object of elements to look into (defaults to elements$)
  • Returns: VueformElement|null

Returns an element by its path.

siblings$

  • Arguments:
    • {string} path* - path of the element
  • Returns: void

Returns the siblings of an element.

submit

  • Returns: Promise

Validates and prepares elements then submits the form (async).

load

  • Arguments:
    • {string} value* - the value to be loaded
    • {boolean} format - whether the loaded value should be formatted with formatLoad (default: false)
  • Returns: Promise

Loads data to the form using optional formatLoad formatter.

update

  • Arguments:
    • {object} data* - data to update with
    • {object} path - the path of the element to update (default: null)
  • Returns: void

Updates the form data. Can be used to update a single element by providing the element's path as second option.

clear

  • Returns: void

Clears the forms data.

reset

  • Returns: void

Resets the form's data to default state. Also resets all the validation state for the elements.

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

Validates all elements (async) which weren't validated before. If validateOn does not contain change it will validate all elements on each call.

clean

  • Returns: void

Sets all elements' dirty to false.

resetValidators

  • Returns: void

Sets all element validators to default state.

Events

Events emitted by the component.

change

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

Triggered when the forms data is changed.

reset

Triggered when the form is reseted using reset().

clear

Triggered when the form is cleared using clear().

submit

  • Params:
    • {component} form$ - the form's component

Triggered when the form is being submitted, after validation is checked and elements are prepared.

success

  • Params:
    • {Response} response - axios Response object
    • {component} form$ - the form's component

Triggered when the server returns 2XX response after submitting the form.

error

  • Params:
    • {Error} error - the Error object
    • {object} details - additional information for the error, including stage property ("prepare|submit") which indicates when the error was thrown.
    • {component} form$ - the form's component

Triggered when an error is thrown when preparing elements or submitting the form.

response

  • Params:
    • {Response} response - axios Response object
    • {component} form$ - the form's component

Triggered when the server returns a response after submitting the form.

language

  • Params:
    • {string} language - the selected language

Triggered when a language is selected.

beforeCreate

  • Params:
    • {component} form$ - the form's component

Triggered in beforeCreate hook.

created

  • Params:
    • {component} form$ - the form's component

Triggered in created hook.

beforeMount

  • Params:
    • {component} form$ - the form's component

Triggered in beforeMount hook.

mounted

  • Params:
    • {component} form$ - the form's component

Triggered in mounted hook.

beforeUpdate

  • Params:
    • {component} form$ - the form's component

Triggered in beforeUpdate hook.

updated

  • Params:
    • {component} form$ - the form's component

Triggered in updated hook.

beforeUnmount

  • Params:
    • {component} form$ - the form's component

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

unmounted

  • Params:
    • {component} form$ - the form's component

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

Slots

The slots of the component.

default

Can be used to render elements. When using default slot other form components (like FormSteps or FormErrors) are automatically added to the form and elements are rendered in FormElements component. If you want to use inline form components (eg. FormSteps) #empty slot should be used.

vue
<Vueform>
  <TextElement name="name" ... />
  <TextareaElement name="bio" ... />
</Vueform>

empty

Can be used to render form components. When using empty slot no form components are being added to the form. If you want to display form errors for example you need to add FormErrors component. Elements should be put into a FormElements component.

vue
<Vueform>
  <template #empty>
    <FormSteps>
      <!-- ... --->
    </FormSteps>
    <FormMessages v-if="showErrors" />
    <FormElements>
      <TextElement name="name" ... />
      <TextareaElement name="bio" ... />
    </FormElements>
  </template>
</Vueform>

Here's the default template for Vueform component:

vue
<!-- From: @vueform/vueform/themes/blank/templates/Vueform.vue -->

<template>
  <form
    :class="classes.form"
    @submit.prevent="submit"
  >
    <slot name="empty">
      <FormMessages v-if="showMessages"/>
      <FormErrors v-if="showErrors"/>
      <FormLanguages v-if="showLanguages"/>
      <FormTabs v-if="showTabs"/>
      <FormSteps v-if="showSteps"/>
      <FormElements><slot/></FormElements>
      <FormStepsControls v-if="showStepsControls"/>
    </slot>
  </form>
</template>
👋 Hire Vueform team for form customizations and developmentLearn more