Composables
useConvexMutation
Execute Convex mutations to write data.
Call a Convex mutation to write data. Mutations are transactional and run on the server.
Usage
app/components/AddTask.vue
<script setup lang="ts">
import { api } from '#convex/api'
const { mutate: addTask, isLoading, error } = useConvexMutation(api.tasks.add)
const title = ref('')
async function handleSubmit() {
await addTask({ title: title.value, userId: 'user_123' })
title.value = ''
}
</script>
<template>
<form @submit.prevent="handleSubmit">
<input v-model="title" :disabled="isLoading" placeholder="New task...">
<button :disabled="isLoading">
Add
</button>
<p v-if="error">
{{ error.message }}
</p>
</form>
</template>
Parameters
| Parameter | Type | Description |
|---|---|---|
mutation | FunctionReference | The Convex mutation to call |
Return Values
| Property | Type | Description |
|---|---|---|
mutate | (args) => Promise<T> | Call the mutation |
isLoading | Ref<boolean> | True while running |
error | Ref<Error | null> | Error if mutation failed |
Return Value from Mutation
The mutate function returns the mutation's result:
app/components/CreateDoc.vue
<script setup lang="ts">
import { api } from '#convex/api'
const { mutate: createDoc } = useConvexMutation(api.documents.create)
async function handleCreate() {
const docId = await createDoc({ title: 'New Document' })
navigateTo(`/docs/${docId}`)
}
</script>
Error Handling
Handle errors with try/catch or the error ref:
app/components/DeleteTask.vue
<script setup lang="ts">
import { api } from '#convex/api'
const { mutate: deleteTask, error } = useConvexMutation(api.tasks.remove)
async function handleDelete(id: string) {
try {
await deleteTask({ id })
}
catch (e) {
console.error('Delete failed:', e)
}
}
</script>
<template>
<div>
<button @click="handleDelete(taskId)">
Delete
</button>
<p v-if="error" class="text-red-500">
{{ error.message }}
</p>
</div>
</template>
Optimistic Updates
Convex handles optimistic updates automatically. When you call a mutation, queries that depend on the affected data update immediately with the expected result, then reconcile with the server response.