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.
components โ
- Type:
object
- Default:
{}
Components to register when tree-shaking.
// vueform.config.js
import {
EditorWrapper,
EditorElement,
} from '@vueform/vueform/core'
export default {
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 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',
}
}
// ...
}