signal.mutation

Execute a GraphQL mutation and track its state using reactive Signals.

API

Apollo.signal.mutation<TData, TVariables>(
  mutation: DocumentNode | TypedDocumentNode<TData, TVariables>,
  options?: SignalMutationOptions<TData, TVariables>
): SignalMutation<TData, TVariables>

Accepts a required GraphQL mutation document and an optional SignalMutationOptions object.

Returns a SignalMutation<TData, TVariables> instance. This object provides several reactive Signals (result, data, loading, error, called) that reflect the state of the mutation execution. It also includes methods for interaction, primarily mutate and reset.

Options

Property	Type	Description
optimisticResponse?	Unmasked<NoInfer<TData>> | ((vars: TVariables, { IGNORE }: { IGNORE: IgnoreModifier }) => Unmasked<NoInfer<TData>> | IgnoreModifier)	By providing either an object or a callback function that, when invoked after a mutation, allows you to return optimistic data and optionally skip updates via the IGNORE sentinel object, Apollo Client caches this temporary (and potentially incorrect) response until the mutation completes, enabling more responsive UI updates. For more information, see Optimistic mutation results.
updateQueries?	MutationQueryReducersMap<TData>	A MutationQueryReducersMap, which is map from query names to mutation query reducers. Briefly, this map defines how to incorporate the results of the mutation into the results of queries that are currently being watched by your application.
refetchQueries?	((result: NormalizedExecutionResult<Unmasked<TData>>) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude	An array (or a function that returns an array) that specifies which queries you want to refetch after the mutation occurs. Each array value can be either: - An object containing the query to execute, along with any variables - A string indicating the operation name of the query to refetch
awaitRefetchQueries?	boolean	If true, makes sure all queries included in refetchQueries are completed before the mutation is considered complete. The default value is false (queries are refetched asynchronously).
update?	MutationUpdaterFunction<TData, TVariables, TCache>	A function used to update the Apollo Client cache after the mutation completes. For more information, see Updating the cache after a mutation.
onQueryUpdated?	OnQueryUpdated<any>	Optional callback for intercepting queries whose cache data has been updated by the mutation, as well as any queries specified in the refetchQueries: [...] list passed to client.mutate. Returning a Promise from onQueryUpdated will cause the final mutation Promise to await the returned Promise. Returning false causes the query to be ignored.
errorPolicy?	ErrorPolicy	Specifies how the mutation handles a response that returns both GraphQL errors and partial results. For details, see GraphQL error policies. The default value is none, meaning that the mutation result includes error details but not partial results.
context?	DefaultContext	If you're using Apollo Link, this object is the initial value of the context object that's passed along your link chain.
fetchPolicy?	MutationFetchPolicy	Provide no-cache if the mutation's result should not be written to the Apollo Client cache. The default value is network-only (which means the result is written to the cache). Unlike queries, mutations do not support fetch policies besides network-only and no-cache.
keepRootFields?	boolean	To avoid retaining sensitive information from mutation root field arguments, Apollo Client v3.4+ automatically clears any ROOT_MUTATION fields from the cache after each mutation finishes. If you need this information to remain in the cache, you can prevent the removal by passing keepRootFields: true to the mutation. ROOT_MUTATION result data are also passed to the mutation update function, so we recommend obtaining the results that way, rather than using this option, if possible.
onData?	(data: TData, options: MutationOptions<TData, TVariables>) => void	Callback executed when the mutation completes successfully.
onError?	(error: ErrorLike, options: MutationOptions<TData, TVariables>) => void	Callback executed when the mutation encounters an error.

Signals

Signal	Type	Description
result	Signal<SignalMutationResult<TData>>	The mutation result, containing data, loading, and error and called.
loading	Signal<boolean>	If true, the mutation is currently in flight.
data	Signal<TData | undefined>	The data returned from the mutation.
error	Signal<ErrorLike | undefined>	The error encountered during the mutation.
called	Signal<boolean>	If true, the mutation's mutate method has been called.

Methods

Method	Description
mutate(executeOptions?: SignalMutationExecutionOptions<TData, TVariables>)	Execute the mutation with the provided variables and options.
reset()	Reset the mutation result to its initial state.

Executing a mutation

To execute a mutation, inject Apollo and call signal.mutation with the GraphQL mutation document. Then, call the mutate method on the returned SignalMutation instance, passing execution options (like variables).

First, we'll create a GraphQL mutation named UpdateBook:

library/gql/book.graphql

mutation UpdateBook($id: ID!, $book: UpdateBookInput!) {
  updateBook(id: $id, book: $book) {
    ...BookFragment
  }
}

Saving book.graphql will trigger codegen of UPDATE_BOOK_MUTATION typed gql document in /graphql/types.ts file as per our setup.

For more information about codegen and how it works, please refer to the Codegen section.

tip

We have used the same BookFragment from our previous query example, that way Apollo Client will automatically normalize and update the cache with the new data returned from the mutation.
This will automatically update any active QueryObservable instances that are watching the same data, and the UI will display the new data without any additional effort by the developer.

Next, define the mutation in your component:

library/books/books.component.ts

import { Apollo } from '@apollo-orbit/angular';
import { UPDATE_BOOK_MUTATION, UpdateBookInput } from '../graphql/types';

@Component({
  selector: 'app-books',
  templateUrl: './books.component.html'
})
export class BooksComponent {
  private readonly apollo = inject(Apollo);
  private readonly notificationService = inject(NotificationService);

  protected readonly updateBookMutation = this.apollo.signal.mutation(UPDATE_BOOK_MUTATION);

  protected async updateBook(id: string, book: UpdateBookInput): Promise<void> {
    const { error, data } = await this.updateBookMutation.mutate({ variables: { id, book } });

    // Optionally handle the result
    if (error) {
      this.notificationService.error(`Failed to update book '${book.name}': ${error.message}`)
    } else if (data) {
      this.notificationService.success(`Book '${data.updateBook.name}' was updated successfully.`)
    }
  }
}

info

By default, signal.mutation has errorPolicy set to all
This ensures that the promise returned by mutate() always resolves without a rejection even if the mutation encounters errors. Removing the need for try...catch or catching unhandled promise rejections.

Finally, use the signals in the template to provide feedback:

library/books/books.component.ts

<h3>Books</h3>

@if (updateBookMutation.called()) { <!-- Optional check -->
  @if (updateBookMutation.error(); as error) {
    <div class="error">Error: {{ error.message }}</div>
  } @else if (updateBookMutation.data(); as data) {
    <div class="success">Book '{{ data.updateBook.name }}' was updated successfully.</div>
  }
}

...

<button (click)="updateBook(...)" [disabled]="updateBookMutation.loading()">
  {{ updateBookMutation.loading() ? 'Updating...' : 'Update' }}
</button>

note

Compared to the observable-based mutate method, signal.mutation neatly encapsulates the mutation state into a single SignalMutation instance, removing the need for tracking state in separate loading and error signals as shown in the mutate example.