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
  • Default: {}

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',
    }
  }
  // ...
}