Vueform

Renders the form.

Basic Usage

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

<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
<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
<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
<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
<Vueform :steps-controls="false" ... />

Whether FormStepsControls component should be displayed when steps are defined.

validateOn

  • Type: string
<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.

displayErrors

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

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

displayMessages

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

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

messages

  • Type: object
<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
<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 handles the submit:

<!-- Using a function to upload file -->
<Vueform :endpoint="async function(data, form$){
  const formData = data // data returned by `formData` option

  /* submit form data */
}" ... />

method

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

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

prepare

  • Type: function
<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
<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
<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
<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
<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
<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
<Vueform :default="{ name: 'John Doe', email: 'john@doe.com' }" ... />
  <TextElement name="name" />
  <TextElement name="email" />
</Vueform>

Sets the default data for the form.

formatData

  • Type: function
<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
<VueformElement :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
<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
<Vueform :disabled="true" ... />

Prevents the form from being submitted.

columns

  • Type: object
<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):

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

forceLabels

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

Whether empty labels should be displayed for elements.

floatPlaceholders

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

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

size

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

The default size of the elements.

view

  • Type: string
<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
<Vueform :views="{
  ComponentName: 'alt'
}" ... />

The name of the default views for the child components.

Learn more about views here.

addClasses

  • Type: object
<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.

Learn more about adding classes here.

addClass

  • Type: array|object|string
<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.

Learn more about adding classes here.

removeClasses

  • Type: object
<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.

Learn more about removing classes here.

removeClass

  • Type: array|object
<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.

Learn more about removing classes here.

replaceClasses

  • Type: object
<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.

Learn more about replacing classes here.

replaceClass

  • Type: object
<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.

Learn more about replacing classes here.

overrideClasses

  • Type: object
<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.

Learn more about overriding classes here.

overrideClass

  • Type: array|object|string
<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.

Learn more about overriding classes here.

templates

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

<script>
import { markRaw } from 'vue' // '@vue/composition-api' in Vue.js 2
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
<Vueform :presets="['preset1', 'preset2']" ... />

The presets to be applied on a form level.

Learn more about presets classes here.

multilingual

  • Type: boolean
<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
<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
<Vueform language="zh" ... />

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

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.

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.

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: component
  • Group: computed

The form component instance (self).

Methods

The methods of the component.

.convertFormData(data)

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

Converts form data to FormData.

.send()

  • Returns: void

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

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

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

Sets current language when using multilingual.

.handleSubmit()

  • Returns: void

Handles submit event.

.el$(path)

  • Arguments:
    • {string} path - path of the element
  • Returns: component|null

Returns an element by its path.

.siblings$(path)

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

Returns the siblings of an element.

.submit()

  • Returns: void

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

.load(value, format)

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

Loads data to the form using optional formatLoad formatter.

.update(data, path)

  • 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(event, callback)

  • 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(event)

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

Removes all listeners for an event.

.fire(args)

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

Fires and emits an event.

.validate()

  • Returns: void

Validates all elements (async).

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

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

<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>
 
Table of contents