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 vueform from '@vueform/vueform/themes/vueform'
import en from '@vueform/vueform/locales/en'

export default {
  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

export default {
  env: 'production',
  // ...
}

plugins

Type: array
Default: []

Registers plugins.

// vueform.config.js

import { plugin } from '@vueform/vueform'

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

Learn more about plugins here.

elements

Type: array
Default: []

Registers custom elmenets.

// vueform.config.js

import RatingElement from './path/to/RatingElement.vue'

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

Learn more about creating elements 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 vueform from '@vueform/vueform/themes/vueform'

export default {
  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 CustomElementDescription from '/path/to/custom/CustomElementDescription.vue'

export default {
  templates: {
    ElementDescription,
  }
  // ...
}

Learn more about overriding templates here.

views

Type: object
Default: {}

The default views for each component.

// vueform.config.js

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

Learn more about views here.

size

Type: string
Default: md

The default size of components.

// vueform.config.js

export default {
  size: 'lg',
  // ...
}

Learn more about size here.

classHelpers

Type: boolean
Default: false

Enables class helpers unless env is production.

// vueform.config.js

export default {
  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

export default {
  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

export default {
  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

export default {
  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

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

Learn more about overriding classes here.

presets

Type: object
Default: {}

Preset definitions.

// vueform.config.js

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

Learn more about presets here.

usePresets

Type: array
Default: []

The list of presets to apply globally.

// vueform.config.js

export default {
  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

export default {
  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

export default {
  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

export default {
  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

export default {
  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

export default {
  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

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

language

Type: string
Default: en

Sets the default language when using multilingual: true.

// vueform.config.js

export default {
  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 { en } from '@vueform/vueform/locales/en'

export default {
  locales: {
    en,
  },
  // ...
}

locale

Type: string
Default: null
Required: true

Sets the current locale.

// vueform.config.js
import { en } from '@vueform/vueform/locales/en'

export default {
  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

export default {
  fallbackLocale: 'zh',
  // ...
}

orderFrom

Type: number
Default: 1

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

// vueform.config.js

export default {
  orderFrom: 0,
  // ...
}

rules

Type: object
Default: {}

Registers custom validation rules.

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

export default {
  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

export default {
  validateOn: 'step',
  // ...
}

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

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

formData

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

Sets the data object submitted by Vueform globally.

// vueform.config.js

export default {
  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

export default {
  async beforeSend(form$) {
    let active = (await form$.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 axios from 'axios'

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

export default {
  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

export default {
  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. Supported providers are google and algolia.

// vueform.config.js

export default {
  locationProvider: 'algolia',
  // ...
}

Learn more about location providers here.

services

Type: object
Default: see below

Global configuration for services. Default:

// Default for `config.services`:

{
  algolia: {
    app_id: '',
    api_key: '',
  }
}

Example:

// vueform.config.js

export default {
  services: {
    algolia: {
      app_id: 'YOUR_ALGOLIA_APP_ID',
      api_key: 'YOUR_ALGOLIA_API_KEY',
    }
  }
  // ...
}