Formisch
Build forms with Formisch and Valibot on top of kappa-ui's Field components.
Formisch is a small, schema-first form library from the author of Valibot. You describe the form once as a Valibot schema, and Formisch derives its input and output types, validates against it and tracks each field's state. kappa-ui has no form component of its own: Formisch holds the state, and the Field components lay the form out and wire its labels, descriptions and errors.
Bug report
Help us improve by reporting what went wrong.
Installation
pnpm add @formisch/vue valibot
The examples on this page list both as dependencies, so adding one of them with the CLI installs them too.
Anatomy
<script setup lang="ts">
import { Form, Field as FormischField, useForm } from '@formisch/vue'
import * as v from 'valibot'
import type { ComponentPublicInstance } from 'vue'
import { Field, FieldError, FieldLabel } from '@/components/ui/field'
import { Input } from '@/components/ui/input'
const Signup = v.object({
email: v.pipe(v.string(), v.email('Enter a valid email address.')),
})
const form = useForm({ schema: Signup, initialInput: { email: '' } })
const element = (control: Element | ComponentPublicInstance | null) =>
control && '$el' in control ? control.$el : control
</script>
<template>
<Form :of="form" @submit="(output) => save(output)">
<FormischField v-slot="field" :of="form" :path="['email']">
<Field :invalid="field.errors !== null">
<FieldLabel>Email</FieldLabel>
<Input
v-model="field.input"
v-bind="field.props"
:ref="(control) => field.props.ref(element(control))"
type="email"
/>
<FieldError :errors="field.errors" />
</Field>
</FormischField>
</Form>
</template>
Formisch has a Field component too. The examples import it as FormischField and keep kappa-ui's under its own name.
useFormcreates the form store from the schema and the starting values.Formrenders the<form>, prevents the page reload, validates, and calls@submitonly with valid data, typed from the schema. It also setsnovalidate, so the browser's own messages stay out of the way.FormischFieldgives its slot the field's state:input,errors, andpropsfor the element. Therefline passes the native input to Formisch, see Controls.- kappa-ui's
Fieldtakesinvalidand passes it on. The control inside getsaria-invalid, is described by the error, and turns--destructive; the label turns with it. You set the state once, on the field. FieldErrortakes Formisch's error list as it is and shows one message, or a list when there are several.
Validation
Formisch validates on submit, and after the first submit on every input. Change either with validate and revalidate:
const form = useForm({
schema: Signup,
validate: 'blur',
revalidate: 'input',
})
| Option | Values | Default |
|---|---|---|
validate | 'initial', 'blur', 'input', 'submit' | 'submit' |
revalidate | 'blur', 'input', 'submit' | 'input' |
Errors from the server go in with setErrors, and show up in the same FieldError:
import { setErrors } from '@formisch/vue'
setErrors(form, { path: ['email'], errors: ['This email is already registered.'] })
Controls
Text controls, Input and Textarea, take the value with v-model="field.input" and the element props with v-bind="field.props". The props give the element its name and tell Formisch when it gains and loses focus.
Formisch also registers the element through field.props.ref, so a submit with errors can move focus to the first invalid field. A ref on a component receives the component, not its element, so hand Formisch the element: both controls expose their native <input> or <textarea> as $el, and the element helper from the anatomy above unwraps it.
<Input
v-model="field.input"
v-bind="field.props"
:ref="(control) => field.props.ref(element(control))"
/>
The other controls take v-model="field.input" alone. A select also takes the field's name for the hidden native select, a checkbox group binds its array of values, and a radio group or switch binds its single value.
For a group of checkboxes or radios, put invalid on the FieldSet instead of a Field: the whole group turns red and is described by the error. A switch that has to be on uses v.value(true) in the schema.
Arrays
FieldArray lists the items of an array field, with a stable key for each. insert and remove add and remove items, and move, swap and replace reorder them, all with the form as the first argument. The array's own errors, such as a minimum or maximum length, arrive on the FieldArray slot.
Resetting
reset(form) returns every field to its starting value and clears the errors. Pass initialInput to reset to new values, for example after saving:
import { reset } from '@formisch/vue'
reset(form, { initialInput: saved })