Skip to content

ApolloMutation component ​

This component allows you to send mutations from your template.

Use props to configure the component and the default slot to interact with it.

Example:

vue
<ApolloMutation
  :mutation="gql => gql`
    mutation DoStuff ($name: String!) {
      someWork (name: $name) {
        success
        timeSpent
      }
    }
  `"
  :variables="{
    name
  }"
  @done="onDone"
>
  <template v-slot="{ mutate, loading, error }">
    <button :disabled="loading" @click="mutate()">Click me</button>
    <p v-if="error">An error occurred: {{ error }}</p>
  </template>
</ApolloMutation>
<ApolloMutation
  :mutation="gql => gql`
    mutation DoStuff ($name: String!) {
      someWork (name: $name) {
        success
        timeSpent
      }
    }
  `"
  :variables="{
    name
  }"
  @done="onDone"
>
  <template v-slot="{ mutate, loading, error }">
    <button :disabled="loading" @click="mutate()">Click me</button>
    <p v-if="error">An error occurred: {{ error }}</p>
  </template>
</ApolloMutation>

Props ​

mutation ​

GraphQL query (transformed by graphql-tag) or a function that receives the gql tag as argument and should return the transformed query.

vue
<ApolloMutation
  :mutation="gql => gql`
    mutation DoStuff ($name: String!) {
      someWork (name: $name) {
        success
        timeSpent
      }
    }
  `"
/>
<ApolloMutation
  :mutation="gql => gql`
    mutation DoStuff ($name: String!) {
      someWork (name: $name) {
        success
        timeSpent
      }
    }
  `"
/>

variables ​

Object of GraphQL variables.

vue
<ApolloMutation
  :variables="{
    name
  }"
/>
<ApolloMutation
  :variables="{
    name
  }"
/>

optimisticResponse ​

Optimistic UI is a pattern that you can use to simulate the results of a mutation and update the UI even before receiving a response from the server. Once the response is received from the server, the optimistic result is thrown away and replaced with the actual result.

Optimistic UI provides an easy way to make your UI respond much faster, while ensuring that the data becomes consistent with the actual response when it arrives.

See optimistic UI

vue
<ApolloMutation
  :optimisticResponse="{
    __typename: 'Mutation',
    someWork: {
      __typename: 'SomeWorkPayload',
      success: true,
      timeSpent: 100,
    },
  }"
/>
<ApolloMutation
  :optimisticResponse="{
    __typename: 'Mutation',
    someWork: {
      __typename: 'SomeWorkPayload',
      success: true,
      timeSpent: 100,
    },
  }"
/>

update ​

When you execute a mutation, you modify back-end data. If that data is also present in your Apollo Client cache, you might need to update your cache to reflect the result of the mutation.

If a mutation modifies multiple entities, or if it creates or deletes entities, the Apollo Client cache is not automatically updated to reflect the result of the mutation. To resolve this, you can include an update function.

The purpose of an update function is to modify your cached data to match the modifications that a mutation makes to your back-end data.

See updating cache after mutation

vue
<template>
  <ApolloMutation
    :update="update"
  />
</template>

<script>
export default {
  methods: {
    update(cache, { data: { addTodo } }) {
      cache.modify({
        fields: {
          todos(existingTodos = []) {
            const newTodoRef = cache.writeFragment({
              data: addTodo,
              fragment: gql`
                fragment NewTodo on Todo {
                  id
                  type
                }
              `,
            })
            return [...existingTodos, newTodoRef]
          },
        },
      })
    },
  },
}
</script>
<template>
  <ApolloMutation
    :update="update"
  />
</template>

<script>
export default {
  methods: {
    update(cache, { data: { addTodo } }) {
      cache.modify({
        fields: {
          todos(existingTodos = []) {
            const newTodoRef = cache.writeFragment({
              data: addTodo,
              fragment: gql`
                fragment NewTodo on Todo {
                  id
                  type
                }
              `,
            })
            return [...existingTodos, newTodoRef]
          },
        },
      })
    },
  },
}
</script>

refetchQueries ​

In some cases, just using dataIdFromObject is not enough for your application UI to update correctly. For example, if you want to add something to a list of objects without refetching the entire list, or if there are some objects that to which you can't assign an object identifier, Apollo Client cannot update existing queries for you. Read on to learn about the other tools at your disposal.

refetchQueries is the simplest way of updating the cache. With refetchQueries you can specify one or more queries that you want to run after a mutation is completed in order to refetch the parts of the store that may have been affected by the mutation.

See refetching queries after mutation

vue
<template>
  <ApolloMutation
    :refetchQueries="refetchQueriesAfterMyMutation"
  />
</template>

<script>
import gql from 'graphql-tag'

export default {
  computed: {
    refetchQueriesAfterMyMutation () {
      return [{
        query: gql`
          query UpdateCache($repoName: String!) {
            entry(repoFullName: $repoName) {
              id
              comments {
                postedBy {
                  login
                  html_url
                }
                createdAt
                content
              }
            }
          }
        `,
        variables: { repoName: 'apollographql/apollo-client' },
      }]
    },
  },
}
</script>
<template>
  <ApolloMutation
    :refetchQueries="refetchQueriesAfterMyMutation"
  />
</template>

<script>
import gql from 'graphql-tag'

export default {
  computed: {
    refetchQueriesAfterMyMutation () {
      return [{
        query: gql`
          query UpdateCache($repoName: String!) {
            entry(repoFullName: $repoName) {
              id
              comments {
                postedBy {
                  login
                  html_url
                }
                createdAt
                content
              }
            }
          }
        `,
        variables: { repoName: 'apollographql/apollo-client' },
      }]
    },
  },
}
</script>

clientId ​

Id of the Apollo Client used by the query (defined in ApolloProvider clients option)

vue
<ApolloMutation
  clientId="myClient"
/>
<ApolloMutation
  clientId="myClient"
/>

tag ​

String HTML tag name (default: div); if undefined, the component will be renderless (the content won't be wrapped in a tag)

vue
<ApolloMutation
  tag="span"
/>
<ApolloMutation
  tag="span"
/>

context ​

Pass down the Apollo link chain a context object.

See apollo context

vue
<ApolloMutation
  :context="{
    answer: 42,
  }"
/>
<ApolloMutation
  :context="{
    answer: 42,
  }"
/>

Slot props ​

mutate ​

Signature:

ts
mutate(options = null): Promise<FetchResult>
mutate(options = null): Promise<FetchResult>

Function to call the mutation. You can override the mutation options (for example: mutate({ variables: { foo: 'bar } })).

vue
<ApolloMutation>
  <template v-slot="{ mutate }">
    <button @click="mutate({ variables: { myVar: 42 } })">Click me</button>
  </template>
</ApolloMutation>
<ApolloMutation>
  <template v-slot="{ mutate }">
    <button @click="mutate({ variables: { myVar: 42 } })">Click me</button>
  </template>
</ApolloMutation>

loading ​

Boolean indicating that the request is in flight.

vue
<ApolloMutation>
  <template v-slot="{ loading }">
    <button :disabled="loading">Click me</button>
  </template>
</ApolloMutation>
<ApolloMutation>
  <template v-slot="{ loading }">
    <button :disabled="loading">Click me</button>
  </template>
</ApolloMutation>

error ​

Eventual error for the last mutation call.

vue
<ApolloMutation>
  <template v-slot="{ error }">
    <p v-if="error">An error occurred: {{ error }}</p>
  </template>
</ApolloMutation>
<ApolloMutation>
  <template v-slot="{ error }">
    <p v-if="error">An error occurred: {{ error }}</p>
  </template>
</ApolloMutation>

gqlError ​

First GraphQL error if any.

vue
<ApolloMutation>
  <template v-slot="{ gqlError }">
    <p v-if="gqlError">An error occurred: {{ gqlError.message }}</p>
  </template>
</ApolloMutation>
<ApolloMutation>
  <template v-slot="{ gqlError }">
    <p v-if="gqlError">An error occurred: {{ gqlError.message }}</p>
  </template>
</ApolloMutation>

Events ​

done ​

Emitted when a mutation result is received.

Parameters:

  • result: FetchResult
vue
<ApolloMutation
  @done="result => {}"
/>
<ApolloMutation
  @done="result => {}"
/>

error ​

Emitted when a error occurs.

Parameters:

  • error: Error object
vue
<ApolloMutation
  @error="error => {}"
/>
<ApolloMutation
  @error="error => {}"
/>

loading ​

When the loading state changes, the loading event is emitted.

Parameters:

  • loading: Boolean
vue
<ApolloMutation
  @loading="loading => {}"
/>
<ApolloMutation
  @loading="loading => {}"
/>

Released under the MIT License.