Vue Guide

Mutations & Actions

Call Convex mutations for writes, call actions for side effects, and use optimistic updates where they belong.

Use useConvexMutation for writes that happen inside Convex transactions. Use useConvexAction for longer-running or external work that does not fit in a transaction.

Call a mutation

src/components/AddTask.vue

<script setup lang="ts">
import { useConvexMutation } from 'vue-convex'
import { api } from '../convex/_generated/api'

const { mutate, isPending, error } = useConvexMutation(api.tasks.add)

async function onSubmit(text: string) {
  await mutate({ text, completed: false })
}
</script>

Add an optimistic update

Optimistic updates belong on mutations, not actions.

src/components/ToggleTask.ts

import { useConvexMutation } from 'vue-convex'
import { api } from '../convex/_generated/api'

const { mutate } = useConvexMutation(api.tasks.toggle, {
  optimisticUpdate(localStore, args) {
    const tasks = localStore.getQuery(api.tasks.list, {})
    if (!tasks)
      return

    localStore.setQuery(
      api.tasks.list,
      {},
      tasks.map(task => task._id === args.id ? { ...task, completed: !task.completed } : task),
    )
  },
})

If the server rejects the mutation, Convex rolls the optimistic result back.

Call an action

src/components/SendEmail.vue

<script setup lang="ts">
import { useConvexAction } from 'vue-convex'
import { api } from '../convex/_generated/api'

const { execute, isPending, error } = useConvexAction(api.emails.send)

async function onClick() {
  await execute({ to: 'user@example.com', subject: 'Hello' })
}
</script>

Use actions for external APIs, side effects, or orchestration that does not fit inside a Convex transaction.

Choose the right tool

Use case	Preferred API
Create, update, or delete Convex data	`useConvexMutation`
Apply optimistic UI updates	`useConvexMutation`
Call an external API or run longer orchestration	`useConvexAction`

Both helpers need the realtime client, so they run on the client side.

Verify the result

The setup is working when:

isPending reflects in-flight calls
successful calls return data from the server
error captures the latest failure

Next steps

Read Pagination if the mutation updates a paginated list
Read useConvexMutation and useConvexAction for the exact signatures

Edit this pageorReport an issue

Queries

Subscribe to Convex queries with reactive arguments, optional SSR prefetching, and skip logic.

Pagination

Build client-side paginated feeds with useConvexPaginatedQuery and Convex paginated query functions.