## Install
```bash
# pnpm
pnpm add @volverjs/form-vue
# yarn
yarn add @volverjs/form-vue
# npm
npm install @volverjs/form-vue --save
```
## Usage
`@volverjs/form-vue` allow you to create a Vue 3 form with [`@volverjs/ui-vue`](https://github.com/volverjs/ui-vue) components from a [Zod Object](https://zod.dev/?id=objects) schema. It provides two functions: `createForm()` and `useForm()`.
## Plugin
`createForm()` defines globally three components `VvForm`, `VvFormWrapper`, and `VvFormField` through a [Vue 3 Plugin](https://vuejs.org/guide/reusability/plugins.html).
```typescript
import { createApp } from 'vue'
import { createForm } from '@volverjs/form-vue'
// Zod 4. The library also supports Zod 3.25+ via `import { z } from 'zod/v3'`.
import { z } from 'zod'
const schema = z.object({
firstName: z.string(),
lastName: z.string()
})
const app = createApp(App)
const form = createForm({
schema
// lazyLoad: boolean - default false
// updateThrottle: number - default 500
// continuousValidation: boolean - default false
// sideEffects?: (data: any) => void
// scope?: string - Defines a unique scope for the form instance (singletons)
// class?: new (data?: any) => Type - Type constructor for form data
// Example:
// class: class User { constructor(data?: any) { Object.assign(this, data) } }
})
app.use(form)
app.mount('#app')
```
If the schema is omitted, the plugin only share the options to the forms created with the [composable](https://github.com/volverjs/form-vue/#composable).
### VvForm
`VvForm` render a `form` tag and emit a `submit` event. Form data are validated on submit.
A `valid` or `invalid` event is emitted when the form status changes.
```vue
```
The submit can be triggered programmatically with the `submit()` method.
```vue
```
Use the `v-model` directive (or only `:model-value` to set the initial value of form data) or bind the form data.
The form data two way binding is **throttled** by default (500ms) to avoid performance issues. The throttle can be changed with the `updateThrottle` option or prop.
By default form validation **stops** when a **valid state** is reached.
To activate **continuous validation** use the `continuousValidation` option or prop.
```vue
```
## Composable
`useForm()` can be used to create a form programmatically inside a Vue 3 Component.
The **default settings** are **inherited** from the plugin (if it's installed).
```vue
```
### Outside a Vue 3 Component
`useForm()` can create a form also outside a Vue 3 Component, plugin settings are **not inherited**.
```ts
import { useForm } from '@volverjs/form-vue'
import { z } from 'zod'
const schema = z.object({
firstName: z.string(),
lastName: z.string()
})
const {
VvForm,
VvFormWrapper,
VvFormField,
VvFormFieldsGroup,
VvFormTemplate,
formData,
status,
errors,
wrappers
} = useForm(schema, {
lazyLoad: true
})
export default {
VvForm,
VvFormWrapper,
VvFormField,
VvFormFieldsGroup,
VvFormTemplate,
formData,
status,
errors,
wrappers
}
```
### VvFormWrapper
`VvFormWrapper` gives you the validation status of a part of your form.
The wrapper status is invalid if at least one of the fields inside it is invalid.
```vue
There is a validation error
There is a validation error
```
`VvFormWrapper` can be used recursively to create a validation tree. The wrapper status is invalid if **at least one of the fields** inside it or one of its children **is invalid**.
```vue
There is a validation error
There is a validation error
```
The `wrappers` map provides access to form wrapper data.
This allows for better control over form validation state and data management.
```vue
```
### VvFormField
`VvFormField` allow you to render a form field or a [`@volverjs/ui-vue`](https://github.com/volverjs/ui-vue) input component inside a form.
It automatically bind the form data through the `name` attribute. For nested objects, use the `name` attribute with **dot notation**.
```vue
{{ invalidLabel }}
```
To render a [`@volverjs/ui-vue`](https://github.com/volverjs/ui-vue) input component, use the `type` attribute.
By default UI components must be installed globally, they can be lazy-loaded with `lazyLoad` option or prop.
```vue
```
Check the [`VvFormField` documentation](./docs/VvFormField.md) to learn more about form fields.
### VvFormFieldsGroup
`VvFormFieldsGroup` allow you to render a group of form fields inside a form.
It automatically bind the form data through the `names` attribute. For nested objects, use the `names` attribute with **dot notation**.
```vue
```
Alternatively, you can create a custom component to render the group of form fields.
```vue
// MyFieldsGroup.vue
```
An than use it inside the `VvFormFieldsGroup` with the `:is` attribute.
```vue
```
You can also map the form fields to the components v-models. The `:names` attribute can be an object with the component v-models as keys and the form fields names as values.
```vue
```
## VvFormTemplate
Forms can also be created using a template. A template is an **array of objects** that describes the form fields. All properties that are **not listed** below are passed to the component **as props**.
```vue
```
Template items, by default, are rendered as a `VvFormField` component but this can be changed using the `vvIs` property. The `vvIs` property can be a string or a component.
`vvName` refers to the name of the field in the schema and can be a nested property using **dot notation**.
`vvType` refers to the type of the field and can be any of the supported [types](./docs/VvFormField.md#ui-components).
`vvDefaultValue` can be used to set default values for the form item.
`vvShowValid` can be used to show the valid state of the form item.
`vvSlots` can be used to pass a slots to the template item.
`vvChildren` is an array of template items which will be wrapped in the parent item.
Conditional rendering can be achieved using the `vvIf` and `vvElseIf` properties.
```vue
```
`vvElseIf` can be used multiple times. `vvElseIf: true` is like an `else` statement and will be rendered if all previous `vvIf` and `vvElseIf` conditions are false.
`vvIf` and `vvElseIf` can be a string or a function. If it is a string it will be evaluated as a **property** of the form data. If it is a function it will be called with the **form context** as the **first argument** and must return a boolean.
```ts
const templateSchema = [
{
vvIf: ctx => ctx.formData.value.hasUsername,
vvName: 'username',
vvType: 'text',
label: 'Username'
}
]
```
Also the template schema and all template items can be a function.
The function will be called with the **form context** as the **first argument**.
```ts
function templateSchema(ctx) {
return [
{
vvName: 'firstName',
vvType: 'text',
label: `Hi ${ctx.formData.value.firstName}!`
}
]
}
```
```ts
const templateSchema = [
ctx => ({
vvName: 'firstName',
vvType: 'text',
label: `Hi ${ctx.formData.value.firstName}!`
}),
{
vvName: 'username',
type: 'text',
label: 'username'
}
]
```
## Default Object by Zod Schema
`defaultObjectBySchema` creates an object by a [Zod Object Schema](https://zod.dev/?id=objects).
It can be useful to create a **default object** for a **form**. The default object is created by the default values of the schema and can be merged with an other object passed as parameter.
```ts
import { z } from 'zod'
import { defaultObjectBySchema } from '@volverjs/form-vue'
const schema = z.object({
firstName: z.string().default('John'),
lastName: z.string().default('Doe')
})
const defaultObject = defaultObjectBySchema(schema)
// defaultObject = { firstName: 'John', lastName: 'Doe' }
const defaultObject = defaultObjectBySchema(schema, { name: 'Jane' })
// defaultObject = { firstName: 'Jane', lastName: 'Doe' }
```
`defaultObjectBySchema` can be used with nested objects.
```ts
import { z } from 'zod'
import { defaultObjectBySchema } from '@volverjs/form-vue'
const schema = z.object({
firstName: z.string().default('John'),
lastName: z.string().default('Doe'),
address: z.object({
street: z.string().default('Main Street'),
number: z.number().default(1)
})
})
const defaultObject = defaultObjectBySchema(schema)
// defaultObject = { firstName: 'John', lastName: 'Doe', address: { street: 'Main Street', number: 1 } }
```
Other Zod methods are also supported: [`z.nullable()`](https://github.com/colinhacks/zod#nullable), [`z.coerce`](https://github.com/colinhacks/zod#coercion-for-primitives) and [`z.passthrough()`](https://github.com/colinhacks/zod#passthrough).
```ts
import { z } from 'zod'
import { defaultObjectBySchema } from '@volverjs/form-vue'
const schema = z
.object({
firstName: z.string().default('John'),
lastName: z.string().default('Doe'),
address: z.object({
street: z.string().default('Main Street'),
number: z.number().default(1)
}),
age: z.number().nullable().default(null),
height: z.coerce.number().default(1.8),
weight: z.number().default(80)
})
.passthrough()
const defaultObject = defaultObjectBySchema(schema, {
height: '1.9',
email: 'john.doe@test.com'
})
// defaultObject = { firstName: 'John', lastName: 'Doe', address: { street: 'Main Street', number: 1 }, age: null, height: 1.9, weight: 80, email: 'john.doe@test.com' }
```
## Zod 4
`@volverjs/form-vue` supports Zod 4 from `zod@3.25.x` and `zod@4.x.x`. All features and methods are compatible and the usage remains the same, the library automatically detects the Zod version and adapts accordingly.
```typescript
import * as z from 'zod/v4'
import { createForm, useForm, defaultObjectBySchema } from '@volverjs/form-vue'
const schema = z.object({
firstName: z.string(),
lastName: z.string()
})
// Plugin
const form = createForm({
schema
})
// Composable
const { VvForm, VvFormWrapper, VvFormField } = useForm(schema)
// Default Object by Zod Schema
const defaultObject = defaultObjectBySchema(schema, { firstName: 'Jane' })
```
## License
[MIT](http://opensource.org/licenses/MIT)