Vueform ​

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

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

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

<Vueform :steps-controls="false" ... />

Whether FormStepsControls component should be displayed when steps are defined.

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

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

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

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

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

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

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

// vueform.config.js

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

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

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

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

<!-- 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
}" ... />

<Vueform method="POST" ... />

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

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

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

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

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

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

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

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

Sets the default data for the form.

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

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

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

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

<Vueform :disabled="true" ... />

Prevents the form from being submitted.

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

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

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

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

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

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

<Vueform size="sm">
  <TextElement ... />
  <TextareaElement ... />
</Vueform>

The default size of the elements.

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

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

The name of the default views for the child components.

Learn more about views here.

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

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

Learn more about adding classes here.

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

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

Learn more about adding classes here.

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

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

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

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

Learn more about removing classes here.

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

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

Learn more about replacing classes here.

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

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

Learn more about replacing classes here.

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

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

Learn more about overriding classes here.

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

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

Learn more about overriding classes here.

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

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

The presets to be applied on a form level.

Learn more about presets classes here.

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

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

<Vueform language="zh" ... />

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

<Vueform locale="zh" ... />

Overrides the global locale for this form only.

Enables/disables validation for the form globally.

Enables/disables conditions for the form globally.

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

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

The axios cancel token when a request is in progress.

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

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

Whether the form has any tabs.

Whether the form has any errors.

Whether the form has any messages.

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

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

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

Whether the form should show langauge selectors.

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

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

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

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

The tree representation of the form schema.

The flat tree representation of the form schema.

The translation tags of the current locale.

The active locale of the form.

The FormSteps component.

The FormTabs component.

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

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

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

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

Whether the form has any invalid elements.

Whether the form has any elements which were modified.

Whether the form has any elements with pending async validation.

Whether the form has any elements with active debounce process.

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

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

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.

Whether loading state is triggered manually via loading option.

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

The name of the resolved view for Vueform component. This one should be used to determine the component's view in class functions.

The component's template.

The component's classes.

The form component instance (self).

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

Converts form data to FormData.

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

Cancels the form request in progress.

Disabled form validation globally.

Enables form validation globally.

Enables conditions globally.

Disables conditions globally.

Sets current language when using multilingual.

Handles submit event.

Returns an element by its path.

Returns the siblings of an element.

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

Loads data to the form using optional formatLoad formatter.

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

Clears the forms data.

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

Adds a listener for an event.

Removes all listeners for an event.

Fires and emits an event.

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

Sets all elements' dirty to false.

Sets all element validators to default state.

Triggered when the forms data is changed.

Triggered when the form is reseted using reset().

Triggered when the form is cleared using clear().

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

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

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

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

Triggered when a language is selected.

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.

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.

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

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.

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

<!-- 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>