Form submissions
Validate external form values and submit one typed Convex mutation.
useConvexForm is a submission controller, not a form framework. Your component or form library controls values, touched and dirty state, field arrays, focus, navigation, and messages. useConvexForm validates the values with a Standard Schema and sends them to one Convex mutation.
import { type } from 'arktype'
const checkpointSchema = type({
balance: 'number > 0',
note: 'string',
})
const { submit, pending, fieldErrors, formError } = useConvexForm(api.accounts.createCheckpoint, {
schema: checkpointSchema,
toArgs: (values) => ({
balanceCents: Math.round(values.balance * 100),
note: values.note || undefined,
}),
mapError: (error) => ({
form: error.kind === 'server' ? error.message : 'The checkpoint could not be saved.',
}),
})
async function save() {
const result = await submit(
{ balance: balance.value, note: note.value },
{ accountId: accountId.value },
)
if (!result.ok) return
toast.success('Checkpoint saved.')
navigateTo(`/accounts/${accountId.value}`)
}The schema is required. It may validate asynchronously or transform values. toArgs receives the parsed output; any mutation arguments it does not produce become the typed second argument to submit().
Render errors
<template>
<form @submit.prevent="save">
<input v-model.number="balance" :aria-invalid="Boolean(fieldErrors.balance)" />
<p v-for="message in fieldErrors.balance" :key="message">
{{ message }}
</p>
<p v-if="formError" role="alert">{{ formError }}</p>
<button :disabled="pending">Save</button>
</form>
</template>Known top-level issue paths become field errors. Nested paths retain their complete path and route to the matching top-level field. Pathless and unknown paths remain visible as form errors.
mapError receives the safe ConvexCallError. It may map a domain error to known submitted fields or a form message. Without mapError, the form message is error.message. For a server error, that is the text your Convex function put in ConvexError data. Backend validation and authorization remain canonical; browser validation is only faster feedback.
Prefill a form from a query
To edit an existing record, fill the form once from a query result. Then the form values belong to the user.
<script setup lang="ts">
import { type } from 'arktype'
import { api } from '#convex/api'
import type { Id } from '#convex/dataModel'
const props = defineProps<{ projectId: Id<'projects'> }>()
const defaults = { name: '', notifyByEmail: true }
const values = reactive({ ...defaults })
// The project whose settings filled the form. Later edits belong to the user.
const seededFor = ref<Id<'projects'>>()
const {
data: settings,
status,
isStale,
} = await useConvexQuery(api.projectSettings.get, () => ({
projectId: props.projectId,
}))
watchEffect(() => {
// Seed once per project, and only from a current result.
if (seededFor.value === props.projectId) return
if (status.value !== 'success' || isStale.value) return
const current = settings.value
if (current === undefined) return
// `null` is a real result: the project has no settings yet, so the defaults apply.
Object.assign(
values,
current === null ? defaults : { name: current.name, notifyByEmail: current.notifyByEmail },
)
seededFor.value = props.projectId
})
const { submit, pending, fieldErrors, formError } = useConvexForm(api.projectSettings.save, {
schema: type({ name: 'string > 0', notifyByEmail: 'boolean' }),
toArgs: (parsed) => parsed,
})
async function save() {
await submit({ ...values }, { projectId: props.projectId })
}
</script>
<template>
<p v-if="seededFor !== projectId && status === 'error'" role="alert">
The settings could not be loaded.
</p>
<p v-else-if="seededFor !== projectId" aria-busy="true">Loading settings…</p>
<form v-else @submit.prevent="save">
<label>
Name
<input v-model="values.name" name="name" :aria-invalid="Boolean(fieldErrors.name)" />
</label>
<p v-for="message in fieldErrors.name" :key="message">{{ message }}</p>
<label>
<input v-model="values.notifyByEmail" name="notifyByEmail" type="checkbox" />
Email me about changes
</label>
<p v-if="formError" role="alert">{{ formError }}</p>
<button :disabled="pending">Save</button>
</form>
</template>api.projectSettings.get returns the settings document, or null when the project has none. api.projectSettings.save checks that the user may edit the project before it writes.
- Seed only when
status === 'success'andisStaleisfalse. Before that,datais missing or belongs to other arguments. - Compare
datawithundefined, not with!data.nullis a successful result, and it must seed the defaults. With!data, the form never shows for a new project. - Key the seed on the record ID or the query arguments (
seededForabove). WhenprojectIdchanges, the form fills again from the new project. - After the seed, the form ignores live updates on purpose, so a change from another tab never overwrites what the user typed. To show that change, compare
settingswith the saved values and show a notice. - Await the query, so the server render shows the filled form when the server can run the query, and hydration shows the same form. With
server: false, or when the server has no Convex URL or Convex session token, the query isidlewithblockedBy: 'server'on the server, and the form shows the loading text until the browser has the result.
Submission rules
- Expected validation and mutation failures resolve as
{ ok: false, error }. - Success resolves as
{ ok: true, data }. - A second
submit()while one is pending rejects with aConvexCallErrorwith codeSUBMIT_IN_PROGRESSand sends no mutation. Disable the submit button whilependingistrue. reset()returns toidle, clearsdataanderror, and lets a new submission start at once. It cannot cancel or roll back a mutation already accepted by Convex.- An identity change, such as signing out, works like
reset(): the form returns toidleand clears the previous user'sdata,error, and field messages at once. - A reset, identity change, or component disposal prevents an older completion from repopulating state. The older submission still resolves or rejects its own Promise.
- A submission that is retired while its schema or
toArgsstill runs never sends the mutation. It resolves{ ok: false, error }. The code isIDENTITY_CHANGEDwhen the signed-in user changed, andCANCELLEDafterreset()or component disposal. - A submission belongs to the user who called
submit(). When that user changes while the mutation runs, the submission resolves{ ok: false, error }with codeIDENTITY_CHANGED, anderror.callError.outcomeis'unknown': the mutation may have saved. error.callError.outcomeis'not-sent'when the mutation was never sent. See Error types.
Use useConvexMutation directly for concurrent calls, optimistic writes, uploads, autosave, or commands that are not forms. Use useConvexOperation for several mutations that belong together. Use a dedicated Vue form library when you need field registration, touched/dirty state, field arrays, or wizard behavior; pass its values to submit().