Configuration

Learn how to configure Vueform.

Project Configuration

To create a configuration file follow the steps in our Installation Guide.

After that, we can vueform.config.js to set global configuration options:

// vueform.config.js

import { defineConfig } from '@vueform/vueform'
import vueform from '@vueform/vueform/themes/vueform'
import en from '@vueform/vueform/locales/en'

export default defineConfig({
  theme: vueform,
  locales: { en },
  locale: 'en',
})

The configuration should at least contain a theme, locales and locale options.

Configuration Options

Here is the list of available configuration options.

env

Type: string
Default: development

The environment variable. Possible values: production|development.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  env: 'production',
  // ...
})

plugins

Type: array
Default: []

Registers plugins.

// vueform.config.js

import { defineConfig, plugin } from '@vueform/vueform'

export default defineConfig({
  plugins: [
    plugin({
      apply: /^.*Element/,
      setup(props, context, component) {
        // ...
      }
    })
  ]
  // ...
})

Learn more about plugins here.

elements

Type: array
Default: []

Registers custom elmenets.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'
import RatingElement from './path/to/RatingElement.vue'

export default defineConfig({
  elements: [
    RatingElement,
  ]
  // ...
})

Learn more about creating elements here.

components

Type: object
Default: {}

Components to register when tree-shaking.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

import {
  EditorWrapper,
  EditorElement,
} from '@vueform/vueform/core'

export default defineConfig({
  components: [
    EditorWrapper,
    EditorElement,
  ]
  // ...
})

Learn more about tree-shaking here.

theme

Type: object
Default: {}
Required: true

A theme contains templates, classes and styles for all Vueform components. Currently available themes are vueform and tailwind.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'
import vueform from '@vueform/vueform/themes/vueform'

export default defineConfig({
  theme: vueform,
  // ...
})

Learn more about available themes here.

templates

Type: object
Default: {}

Globally replaces component templates provided by the theme.

For example here's how we can replace the template of ElementDescription component:

// vueform.config.js

import { defineConfig } from '@vueform/vueform'
import CustomElementDescription from '/path/to/custom/CustomElementDescription.vue'

export default defineConfig({
  templates: {
    ElementDescription,
  }
  // ...
})

Learn more about overriding templates here.

views

Type: object
Default: {}

The default views for each component.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  views: {
    CheckboxgroupCheckbox: 'tabs'
  },
  // ...
})

Learn more about views here.

size

Type: string
Default: md

The default size of components.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  size: 'lg',
  // ...
})

Learn more about size here.

classHelpers

Type: boolean
Default: false

Enables class helpers unless env is production.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  classHelpers: true,
  // ...
})

Learn more about class helpers here.

addClasses

Type: object
Default: {}

Globally add classes to components provided by theme theme.

For example here's how we can add a class to the container class of ElementDescription:

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  addClasses: {
    ElementDescription: {
      container: 'added-class',
    },
  },
  // ...
})

Learn more about adding classes here.

removeClasses

Type: object
Default: {}

Globally removes classes from components provided by theme theme.

For example here's how we can remove a class from the container class of ElementDescription:

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  removeClasses: {
    ElementDescription: {
      container: 'text-gray-500',
    },
  },
  // ...
})

Learn more about removing classes here.

replaceClasses

Type: object
Default: {}

Globally replaces component classes provided by theme theme.

For example here's how we can replace a class from the container class of ElementDescription:

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  replaceClasses: {
    ElementDescription: {
      container: {
        'text-gray-500': 'text-green-500'
      },
    },
  },
  // ...
})

Learn more about replacing classes here.

overrideClasses

Type: object
Default: {}

Globally overrides component classes provided by theme theme.

For example here's how we can override the container class of ElementDescription:

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  overrideClasses: {
    ElementDescription: {
      container: 'text-green-500',
    },
  },
  // ...
})

Learn more about overriding classes here.

presets

Type: object
Default: {}

Preset definitions.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  presets: {
    presetName: {
      addClasses: {
        // ...
      },
      templates: {
        // ...
      },
      // ...
    }
  }
  // ...
})

Learn more about presets here.

usePresets

Type: array
Default: []

The list of presets to apply globally.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  usePresets: ['preset1', 'preset2'],
  // ...
})

Learn more about presets here.

columns

Type: object
Default: { container: 12, label: 12, wrapper: 12 }

Sets the default column sizes globally.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  columns: {
    container: 12,
    label: 3,
    wrapper: 12,
  }
  // ...
})

Learn more about columns here.

forceLabels

Type: boolean
Default: false

Sets globally whether empty labels should be displayed for elements.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  forceLabels: true,
  // ...
})

floatPlaceholders

Type: boolean
Default: true

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

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  floatPlaceholders: false,
  // ...
})

displayErrors

Type: boolean
Default: true

Sets globally whether error messages from messageBag should be displayed above the form in FormErrors component.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  displayErrors: false,
  // ...
})

displayMessages

Type: boolean
Default: true

Sets globally whether form messages from messageBag should be displayed above the form in FormMessages component.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  displayMessages: false,
  // ...
})

languages

Type: object
Default: { en: 'English' }

Sets the availble languages when using multilingual: true. You can learn more about it at Translating Elements.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  languages: {
    en: 'English',
    zh: 'Chinese',
    nl: 'Dutch',
  },
  // ...
})

language

Type: string
Default: en

Sets the default language when using multilingual: true.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  language: 'zh',
  // ...
})

locales

Type: object
Default: { }
Required: true

Sets the list of available locales. You can learn more about it at Using Locales.

The available locales are:

en

// vueform.config.js

import { defaultConfig } from '@vueform/vueform'
import { en } from '@vueform/vueform/locales/en'

export default defineConfig({
  locales: {
    en,
  },
  // ...
})

locale

Type: string
Default: null
Required: true

Sets the current locale.

// vueform.config.js

import { defaultConfig } from '@vueform/vueform'
import { en } from '@vueform/vueform/locales/en'

export default defineConfig({
  locales: {
    en,
  },
  locale: 'en',
  // ...
})

fallbackLocale

Type: string
Default: en

Sets the fallback locale, which is used when a translation tag is not available in the current locale.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  fallbackLocale: 'zh',
  // ...
})

orderFrom

Type: number
Default: 1

Sets globally whether list order should start from 0 or 1.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  orderFrom: 0,
  // ...
})

rules

Type: object
Default: {}

Registers custom validation rules.

// vueform.config.js
import uppercase from '/path/to/custom/rules/Uppercase.js'

export default defineConfig({
  rules: {
    uppercase,
  }
  // ...
})

Learn more about validation rules here.

validateOn

Type: string
Default: change|step

Sets globally 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.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  validateOn: 'step',
  // ...
})

scrollToInvalid

Type: boolean
Default: true

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

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  scrollToInvalid: false,
  // ...
})

showRequired

Type: array
Default: []

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.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  showRequired: ['label', 'placeholder', 'floating'],
  // ...
})

scrollOnNext

Type: boolean
Default: true

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

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  scrollOnNext: false,
  // ...
})

endpoints

Type: object
Default: see below

Sets default endpoints used by Vueform. Default:

// Default for `config.endpoints`:

{
  submit: {
    url: '/vueform/process',
    method: 'post',
  },
  uploadTempFile: {
    url: '/vueform/file/upload-temp',
    method: 'post',
  },
  removeTempFile: {
    url: '/vueform/file/remove-temp',
    method: 'post',
  },
  removeFile: {
    url: '/vueform/file/remove',
    method: 'post',
  },
  attachment: {
    url: '/vueform/editor/attachment',
    method: 'post',
  },
  activeUrl: {
    url: '/vueform/validators/active_url',
    method: 'post',
  },
  unique: {
    url: '/vueform/validators/unique',
    method: 'post',
  },
  exists: {
    url: '/vueform/validators/exists',
    method: 'post',
  },
}

For example here's how to replace the default form submit endpoint:

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  endpoints: {
    submit: {
      url: '/form/submit',
      method: 'post',
    },
  }
  // ...
})

forceNumbers

Type: boolean
Default: false

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.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  forceNumbers: true,
  // ...
})

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

formData

Type: function
Default: f$ => f$.requestData

Sets the data object submitted by Vueform globally.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  formData(form$) {
    return form$.convertFormData(form$.requestData)
  },
  // ...
})

Learn more about form data here.

beforeSend

Type: function
Default: null

An async function to run each time before a form is submitted. It can stop the submit process by throwing an error. Receives form$ as its first param.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  async beforeSend(form$) {
    let active = (await form$.$vueform.services.axios.post('/user-still-active')).data

    if (!active) {
      throw new Error('User is not active anymore')
    }
  }
  // ...
})

axios

Type: object|axios
Default: {}

There are two ways to use this options.

It accepts an existing & configured axios instance:

// vueform.config.js

import { defineConfig } from '@vueform/vueform'
import axios from 'axios'

axios.defaults.withCredentials = true
// ...

export default defineConfig({
  axios,
  // ...
})

Or if an object is provided it sets global axios configuration. It has two custom options: csrfRequest and onUnauthenticated.

The csrfRequest option is an endpoint object that is used to submit an intermediate request to the server if an initial request returns 401 or 419. The original request will be retried once after receiving a response from csrfRequest endpoint.

The onUnauthenticated option is a function that is called if the request still returns 401 or 419 after calling csrfRequest and repeating the original request.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  axios: {
    withCredentials: true,
    baseURL: '/api/',
    csrfRequest: {
      method: 'get',
      url: '/csrf-cookie',
    },
    onUnauthenticated() {
      location.href = '/sign-in'
    },
  },
  // ...
})

locationProvider

Type: string
Default: google

Sets the default location provider for elements using location service, like LocationElement. Currently the only supported provider is google.

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  locationProvider: 'google',
  // ...
})

Learn more about location providers here.

services

Type: object
Default: see below

Global configuration for services. Default:

// Default for `config.services`:

{
  services: {}
}

Example:

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  services: {
    service_name: {
      service_option_1: '',
      service_option_2: '',
    }
  }
  // ...
})

providers

Type: object

Create and override providers.

Example:

// vueform.config.js

import { defineConfig } from '@vueform/vueform'
import Recaptcha3Provider from './Recaptcha3Provider'

export default defineConfig({
  providers: {
    captcha: {
      recaptcha3: Recaptcha3Provider,
    },
  },
  // ...
})

useProviders

Type: object

Set the default providers.

Example:

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  useProviders: {
    captcha: 'recaptcha3' // once `recaptcha3` is registered as a provider
  },
  // ...
})

providerOptions

Type: object

Default options for registered providers.

Example:

// vueform.config.js

import { defineConfig } from '@vueform/vueform'

export default defineConfig({
  providerOptions: {
    recaptcha2: {
      sitekey: '6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI',
    }
  },
  // ...
})

Configuration ​

Project Configuration ​

Configuration Options ​

env ​

plugins ​

elements ​

components ​

theme ​

templates ​

views ​

size ​

classHelpers ​

addClasses ​

removeClasses ​

replaceClasses ​

overrideClasses ​

presets ​

usePresets ​

columns ​

forceLabels ​

floatPlaceholders ​

displayErrors ​

displayMessages ​

languages ​

language ​

locales ​

locale ​

fallbackLocale ​

orderFrom ​

rules ​

validateOn ​

scrollToInvalid ​

showRequired ​

scrollOnNext ​

endpoints ​

forceNumbers ​

formData ​

beforeSend ​

axios ​

locationProvider ​

services ​

providers ​

useProviders ​

providerOptions ​

Configuration

Project Configuration

Configuration Options

env

plugins

elements

components

theme

templates

views

size

classHelpers

addClasses

removeClasses

replaceClasses

overrideClasses

presets

usePresets

columns

forceLabels

floatPlaceholders

displayErrors

displayMessages

languages

language

locales

locale

fallbackLocale

orderFrom

rules

validateOn

scrollToInvalid

showRequired

scrollOnNext

endpoints

forceNumbers

formData

beforeSend

axios

locationProvider

services

providers

useProviders

providerOptions