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.

Demo

Bug report

Help us improve by reporting what went wrong.

Include the steps that lead to the bug.

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.

  • useForm creates the form store from the schema and the starting values.
  • Form renders the <form>, prevents the page reload, validates, and calls @submit only with valid data, typed from the schema. It also sets novalidate, so the browser's own messages stay out of the way.
  • FormischField gives its slot the field's state: input, errors, and props for the element. The ref line passes the native input to Formisch, see Controls.
  • kappa-ui's Field takes invalid and passes it on. The control inside gets aria-invalid, is described by the error, and turns --destructive; the label turns with it. You set the state once, on the field.
  • FieldError takes 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',
})
OptionValuesDefault
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.

Select

Used for emails and the interface.

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.

Choices
Notifications
Plan

For individuals.

For small teams.

Ask for a code from your phone when you sign in.

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.

Array
Email addresses

Add up to 5 addresses where we can reach you.

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 })