---
title: "Mutations & Actions"
description: "Call Convex mutations for writes, call actions for side effects, and use optimistic updates where they belong."
canonical_url: "https://nuxt-convex.onmax.me/vue-guide/mutations-and-actions"
---
# 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

```vue [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(title: string) {
  await mutate({ title })
}
</script>
```

## Add an optimistic update

Optimistic updates belong on mutations, not actions.

```ts [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, isCompleted: !task.isCompleted } : task),
    )
  },
})
```

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

## Call an action

```vue [src/components/ImportTasks.vue]
<script setup lang="ts">
import { useConvexAction } from 'vue-convex'
import { api } from '../../convex/_generated/api'

const { execute, isPending, error } = useConvexAction(api.tasks.importFromUrl)

async function onClick() {
  const count = await execute({ url: 'https://example.com/tasks.json' })
}
</script>
```

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

## Choose the right tool

<table>
<thead>
  <tr>
    <th>
      Use case
    </th>
    
    <th>
      Preferred API
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Create, update, or delete Convex data
    </td>
    
    <td>
      <code>
        useConvexMutation
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Apply optimistic UI updates
    </td>
    
    <td>
      <code>
        useConvexMutation
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Call an external API or run longer orchestration
    </td>
    
    <td>
      <code>
        useConvexAction
      </code>
    </td>
  </tr>
</tbody>
</table>

Both helpers need the realtime client, so they run in the browser: call them from event handlers. A failed call rejects and sets `error`; use [`isConvexError`](https://nuxt-convex.onmax.me/api-reference/is-convex-error) to read the code of a `ConvexError`. Functions that take no arguments can be called without them: `mutate()`.

## 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](https://nuxt-convex.onmax.me/vue-guide/pagination) if the mutation updates a paginated list
- Read [`useConvexMutation`](https://nuxt-convex.onmax.me/api-reference/use-convex-mutation) and [`useConvexAction`](https://nuxt-convex.onmax.me/api-reference/use-convex-action) for the exact signatures


## Sitemap

See the full [sitemap](https://nuxt-convex.onmax.me/sitemap.md) for all pages.
