useMutation()

The useMutation function allows you to execute GraphQL mutations, it requires a Provider or useClient to be called in the component tree, so make sure to set that up before using useMutation

The useMutation function returns the following properties and functions:

PropertyTypeDescription
dataRef<any/null>The GraphQL mutation result’s data
errorRef<CombinedError>Any errors encountered during mutation execution
execute(variables: object) => Promise<OperationResult<TData>>Executes the mutation and returns the operation result containing data and error values
isDoneRef<boolean>Set to true when the mutation is executed at least once, never resets to false
isFetchingRef<boolean>Set to true when the mutation is executing by calling execute explicitly

Mutation Options

Aside from the mutation itself, the useMutation function accepts an optional second argument containing these options:

PropertyTypeRequiredDescription
context{ headers: Record<string, string> }NoA object to be merged with the fetch options, currently accepts headers. The context can be a reactive ref or computed ref.
clearCacheTagsstring[]NoPassing this will clear the tagged queries cache if they have any of the tags specified
refetchTagsstring[]NoPassing this will clear the tagged queries cache and will trigger a refetch if those queries have any one of the tags specified

Signature and Usage

You can use useMutation like this:

vue<script setup>
import { useMutation } from 'villus';

const LikePost = `
  mutation {
    likePost (id: 123) {
      message
    }
  }
`;

const { data, execute } = useMutation(LikePost);
</script>

useMutation is very simple and doesn’t accept any other arguments, just the mutation.

Reactivity

useMutation does not accept reactive queries or variables, so it is your responsibility to unwrap any reactive values passed to it

For more information on useMutation, check the mutations guide/