---
title: "useConvexMutation"
description: "Reference for the shared mutation composable."
canonical_url: "https://nuxt-convex.onmax.me/api-reference/use-convex-mutation"
---
# useConvexMutation

> Reference for the shared mutation composable.

`useConvexMutation` wraps a generated Convex mutation and tracks pending state and the latest error.

## Import

```ts [Nuxt]
// Auto-imported. Also exported from '#convex'.
const { mutate } = useConvexMutation(api.tasks.add)
```

```ts [Vue]
import { useConvexMutation } from 'vue-convex'
```

## Signature

```ts
function useConvexMutation<Mutation extends FunctionReference<'mutation'>>(
  mutation: Mutation,
  options?: {
    optimisticUpdate?: OptimisticUpdate<FunctionArgs<Mutation>>
  },
): {
  // `args` is optional when the mutation takes none
  mutate: (...args: OptionalRestArgs<Mutation>) => Promise<FunctionReturnType<Mutation>>
  error: Ref<Error | null>
  isPending: ComputedRef<boolean>
}
```

## Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        mutation
      </code>
    </td>
    
    <td>
      <code>
        FunctionReference<'mutation'>
      </code>
    </td>
    
    <td>
      Generated Convex mutation reference
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options.optimisticUpdate
      </code>
    </td>
    
    <td>
      <code>
        OptimisticUpdate<FunctionArgs<Mutation>>
      </code>
    </td>
    
    <td>
      Optional optimistic cache update forwarded to the Convex client
    </td>
  </tr>
</tbody>
</table>

## Return value

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        mutate
      </code>
    </td>
    
    <td>
      <code>
        (args) => Promise<T>
      </code>
    </td>
    
    <td>
      Executes the mutation
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        error
      </code>
    </td>
    
    <td>
      <code>
        Ref<Error | null>
      </code>
    </td>
    
    <td>
      Latest mutation error
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isPending
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef<boolean>
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
      
       while one or more calls are in flight
    </td>
  </tr>
</tbody>
</table>

## Behavior

- Runs over the realtime client. Before it connects, and during SSR, `mutate` rejects with `Convex realtime client is not connected`
- A failed call rejects and sets `error`. Check `ConvexError` data with [`isConvexError`](https://nuxt-convex.onmax.me/api-reference/is-convex-error)
- Supports optimistic updates through the underlying Convex client
- Call it from event handlers, not during SSR. On the server, use [`serverConvexMutation`](https://nuxt-convex.onmax.me/nuxt-module/server-routes)

## Related pages

- [Mutations & Actions](https://nuxt-convex.onmax.me/vue-guide/mutations-and-actions)
- [useConvexAction](https://nuxt-convex.onmax.me/api-reference/use-convex-action)


## Sitemap

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