Form

A form component designed for validation and handling submissions.

Use the Form component to validate form data using any validation library supporting Standard Schema such as Valibot, Zod, Regle, Yup, Joi or Superstruct or your own validation logic.

It works with the FormField component to display error messages around form elements automatically.

Schema validation

It requires two props:

state - a reactive object holding the form's state.
schema - any Standard Schema or Superstruct.

No validation library is included by default, ensure you install the one you need.

{
  "wait": "Loading client-side content..."
}

{
  "wait": "Loading client-side content..."
}

{
  "wait": "Loading client-side content..."
}

{
  "wait": "Loading client-side content..."
}

{
  "wait": "Loading client-side content..."
}

{
  "wait": "Loading client-side content..."
}

Errors are reported directly to the FormField component based on the name or error-pattern prop. This means the validation rules defined for the email attribute in your schema will be applied to <FormField name="email">.

Nested validation rules are handled using dot notation. For example, a rule like { user: z.object({ email: z.string() }) } will be applied to <FormField name="user.email">.

Custom validation

Use the validate prop to apply your own validation logic.

The validation function must return a list of errors with the following attributes:

message - the error message to display.
name - the name of the FormField to send the error to.

It can be used alongside the schema prop to handle complex use cases.

{
  "wait": "Loading client-side content..."
}

Input events

The Form component automatically triggers validation when an input emits an input, change, or blur event.

Validation on input occurs as you type.
Validation on change occurs when you commit to a value.
Validation on blur happens when an input loses focus.

You can control when validation happens this using the validate-on prop.

The form always validates on submit.

validate-on

You can use the useFormField composable to implement this inside your own components.

Error event

You can listen to the @error event to handle errors. This event is triggered when the form is submitted and contains an array of FormError objects with the following fields:

id - the input's id.
name - the name of the FormField
message - the error message to display.

Here's an example that focuses the first input element with an error after the form is submitted:

{
  "wait": "Loading client-side content..."
}

Nesting forms

Use the nested prop to nest multiple Form components and link their validation functions. In this case, validating the parent form will automatically validate all the other forms inside it.

Nested forms directly inherit their parent's state, so you don't need to define a separate state for them. You can use the name prop to target a nested attribute within the parent's state.

It can be used to dynamically add fields based on user's input:

{
  "wait": "Loading client-side content..."
}

Or to validate list inputs:

{
  "wait": "Loading client-side content..."
}

API

Props

Prop	Default	Type
`id`		`string \| number`
`schema`		`Struct<any, any> \| StandardSchemaV1<object, object>` Schema to validate the form state. Supports Standard Schema objects, Yup, Joi, and Superstructs.
`state`		`Partial<any>` An object representing the current state of the form.
`validate`		`(state: Partial<any>): FormError<string>[] \| Promise<FormError<string>[]>` Custom validation function to validate the form state.
`validateOn`	`['blur', 'change', 'input']`	`FormInputEvents[]` The list of input events that trigger the form validation.
`disabled`		`boolean` Disable all inputs inside the form.
`name`		`string` Path of the form's state within it's parent form. Used for nesting forms. Only available if `nested` is true.
`validateOnInputDelay`	`300`	`number` Delay in milliseconds before validating the form on input events.
`transform`	`true as T`	`boolean` If true, applies schema transformations on submit.
`nested`	`false`	`boolean` If true, this form will attach to its parent Form and validate at the same time.
`loadingAuto`	`true`	`boolean` When `true`, all form elements will be disabled on `@submit` event. This will cause any focused input elements to lose their focus state.
`acceptcharset`		`string`
`action`		`string`
`autocomplete`		`string`
`enctype`		`string`
`method`		`string`
`novalidate`		`false \| true \| "true" \| "false"`
`target`		`string`

This component also supports all native <form> HTML attributes.

Slots

Slot	Type
`default`	`{ errors: FormError<string>[]; loading: boolean; }`

Emits

Event	Type
`submit`	`[event: FormSubmitEvent<any>]`
`error`	`[event: FormErrorEvent]`

Expose

You can access the typed component instance using useTemplateRef.

<script setup lang="ts">
const form = useTemplateRef('form')
</script>

<template>
  <B24Form ref="form" />
</template>

This will give you access to the following:

Name	Type
`submit()`	`Promise<void>` Triggers form submission.
`validate(opts: { name?: keyof T \| (keyof T)[], silent?: boolean, nested?: boolean, transform?: boolean })`	`Promise<T>` Triggers form validation. Will raise any errors unless `opts.silent` is set to true.
`clear(path?: keyof T \| RegExp)`	`void` Clears form errors associated with a specific path. If no path is provided, clears all form errors.
`getErrors(path?: keyof T RegExp)`	`FormError[]` Retrieves form errors associated with a specific path. If no path is provided, returns all form errors.
`setErrors(errors: FormError[], name?: keyof T RegExp)`	`void` Sets form errors for a given path. If no path is provided, overrides all errors.
`errors`	`Ref<FormError[]>` A reference to the array containing validation errors. Use this to access or manipulate the error information.
`disabled`	`Ref<boolean>`
`dirty`	`Ref<boolean>` `true` if at least one form field has been updated by the user.
`dirtyFields`	`DeepReadonly<Set<keyof T>>` Tracks fields that have been modified by the user.
`touchedFields`	`DeepReadonly<Set<keyof T>>` Tracks fields that the user interacted with.
`blurredFields`	`DeepReadonly<Set<keyof T>>` Tracks fields blurred by the user.

Theme

app.config.ts

export default defineAppConfig({
  b24ui: {
    form: {
      base: ''
    }
  }
})

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import bitrix24UIPluginVite from '@bitrix24/b24ui-nuxt/vite'

export default defineConfig({
  plugins: [
    vue(),
    bitrix24UIPluginVite({
      b24ui: {
        form: {
          base: ''
        }
      }
    })
  ]
})

FileUpload

A file upload input component.

FormField

A container for form elements with built-in validation and error management.