vue-standard-schema

A set of simple Vue3 composables for handling form submit.

Supports optional optional validation with any Standard Schema compatible validation library, such as Zod, Valibot, ArkType, and others.

Unlike FormKit, VeeValidate and others, keeps things simple and doesn't interfere with neither data storage nor the UI workflow.

Full Typescript support with type inference.

Install

``sh
npm install vue-standard-schema
`

Use

`vue



`

useForm composable

`ts
const {
// All return values are optional to use.
form,
submit,
submitting,
submitted,
errors,
} = useForm({
// All options are optional to provide.
input,
schema,
submit,
onErrors,
// Optional defaults for the return values.
form,
submitting,
submitted,
errors,
})
`

useForm options

$3

(Optional) Input value, or ref, or a getter, of the data to be validated and/or passed to submit.

$3

(Optional) Standard Schema compatible schema (or a function that returns a schema, such as when the schema depends on the context). Works with Zod, Valibot, ArkType, and other Standard Schema compatible libraries.

$3

(Optional) Form submit callback.

Only called if:

- Form is not being submitted at the moment (submitting.value is falsy).
- HTML5 validation passes (if enabled).
- Schema validation passes (if used).

If input and/or schema were provided, the first argument passed to the submit callback is the (possibly validated) form input. The rest of the arguments are the submit function arguments.

During execution, submitting is true.
After successfull execution, submitted is true.

$3

(Optional) Error formatter function that transforms raw Standard Schema issues into the desired format.

See _"Formatting errors"_ below.

$3

(Optional) Error callback.

Called (and awaited) if the validation fails, or if errors.value was set by the submit handler.

$3

Normally, useForm will create and return these refs (see below), but you may optionally provide your own.

For example, this could be used to share the single submitting flag between multiple forms:

`ts
const submitting = ref(false)

const { submit: submit1 } = useForm({
submitting,
async submit() { / ... / }
})

const { submit: submit2 } = useForm({
submitting,
async submit() { / ... / }
})

// submitting will be true during submit of either form.
`

useForm shortcut

All the composable options are optional. If the only option you need is submit, there is a shortcut variant:

`ts
const { submit, submitting } = useForm(async () => {
// submitting is true during this callback.
await api.post()
})
`

useForm return

$3

The form element ref.

Using it with

If there was no input composable option, all arguments are passed as is:

`ts
const { submit, submitting } = useForm(
async (arg1: number, arg2: string, arg3 = false) => {
// Note: no input argument.
await api.post({ arg1, arg2, arg3 })
},
)

// Arguments are type checked:
submit(10, "foo")
submit(20, "bar", true)
`

Custom submit errors

You can set errors inside the submit handler. This will be treated the same way as if errors were produced by the schema.

In particular, this could be used together with onError:

`ts
const { submit, errors } = useForm({
input,
schema,
submit(input) {
if (!validateInput(input)) {
errors.value = [{ message: "Input is invalid." }]
}
},
onErrors(errors) {
// errors here come either from schema validation, or from the submit handler.
console.error(errors)
},
})
`

useParse

useParse reactively runs Standard Schema validation on every input change.

It could be used together with useForm or independently.

Example usage with Valibot:

`vue



``