<link rel="stylesheet" href="/_merged_assets/_static/search/noscript.css">
Apollo Elements Apollo Elements Guides API Blog Toggle darkmode

Interfaces: ApolloMutation

Mutation components affect your app's state by issuing mutations to the GraphQL server. Manage your cache by implementing an updater function, and provide the perception of performance with Optimistic UI.

Mutation components inherit the ApolloElementInterface.

Common interface for mutation elements

See ApolloElementInterface for more information on events

Properties

static

documentType

(read-only)
inherited from ApolloElementElement
'document'|'query'|'mutation'|'subscription'
public

refetchQueries

refetch-queries
RefetchQueriesType<D> | null

A list of query names which will be refetched once this mutation has returned. This is often used if you have a set of queries which may be affected by a mutation and will have to update. Rather than writing a mutation query reducer (i.e. updateQueries) for this, you can refetch the queries that will be affected and achieve a consistent store once these queries return.

public

optimisticResponse

OptimisticResponseType<D, V> | undefined

An object that represents the result of this mutation that will be optimistically stored before the server has actually returned a result.

This is most often used for optimistic UI, where we want to be able to see the result of a mutation immediately, and update the UI later if any errors appear.

public

mutation

ComponentDocument<D, V> | null

The mutation.

public

ignoreResults

boolean

If true, the returned data property will not update with the mutation result.

public

called

(read-only)
boolean

Whether the mutation was called.

public

awaitRefetchQueries

await-refetch-queries
boolean | undefined

Queries refetched as part of refetchQueries are handled asynchronously, and are not waited on before the mutation is completed (resolved). Setting this to true will make sure refetched queries are completed before the mutation is considered done. false by default.

public

client

inherited from ApolloElementElement
ApolloClient<NormalizedCacheObject> | null

The Apollo Client instance.

public

context

inherited from ApolloElementElement
Record<string, unknown> | undefined

Context passed to the link execution chain.

public

controller

inherited from ApolloElementElement
ApolloController<D, V>
public

data

inherited from ApolloElementElement
Data<D> | null

Latest mutation data

public

document

inherited from ApolloElementElement
ComponentDocument<D, V> | null

Operation document.

GraphQL operation document i.e. query, subscription, or mutation. Must be a parsed GraphQL DocumentNode, so use graphql-tag.

public

error

inherited from ApolloElementElement
Error | ApolloError | null

Latest error

public

errorPolicy

inherited from ApolloElementElement error-policy
ErrorPolicy | undefined

Error Policy for the operation.

Much like fetchPolicy, errorPolicy allows you to control how GraphQL errors from the server are sent to your UI code. By default, the error policy treats any GraphQL Errors as network errors and ends the request chain. It doesn't save any data in the cache, and renders your UI with the error property set to an ApolloError. By changing this policy per request, you can adjust how GraphQL Errors are managed by your UI. The possible options for errorPolicy are:

  • none (default): any errors from the request are treated like runtime errors and the observable is stopped (XXX this is default to lower breaking changes going from AC 1.0 => 2.0)
  • ignore: errors from the request do not stop the observable, but also don't call next
  • all: errors are treated like data and will notify observables
public

errors

inherited from ApolloElementElement
readonly GraphQLError[]

Latest errors

public

fetchPolicy

inherited from ApolloElementElement fetch-policy
string | undefined

Fetch Policy for the operation.

If set to 'no-cache', the mutation result will not update the Apollo cache.

public

loading

inherited from ApolloElementElement
boolean

Whether a request is in flight.

public

readyToReceiveDocument

inherited from ApolloElementElement
boolean

True when the element is connected and ready to receive its GraphQL document

public

variables

inherited from ApolloElementElement
Variables<D, V> | null

Mutation variables.

An object that maps from the name of a variable as used in the mutation GraphQL document to that variable's value.

Methods

public

updater

A function which updates the apollo cache when the query responds. This function will be called twice over the lifecycle of a mutation. Once at the very beginning if an optimisticResponse was provided. The writes created from the optimistic data will be rolled back before the second time this function is called which is when the mutation has succesfully resolved. At that point update will be called with the actual mutation result and those writes will not be rolled back.

The reason a DataProxy is provided instead of the user calling the methods directly on ApolloClient is that all of the writes are batched together at the end of the update, and it allows for writes generated by optimistic data to be rolled back.

Examples

Updating a query
updater(cache, result) {
  cache.writeQuery({
    query: MyProfileQuery,
    data: { profile: result.data.updateMyProfile },
  });
}

Parameters

params

Parameters<MutationUpdaterFn<Data<D>, Variables<D, V>>>

Returns

ReturnType<MutationUpdaterFn<Data<D>, Variables<D, V>>>
public

onError

Callback for when an error occurs in mutation.

Parameters

_error

Error

Returns

void
public

onCompleted

Callback for when a mutation is completed.

Parameters

_data

Data<D>

Returns

void
public

mutate

This resolves a single mutation according to the options specified and returns a Promise which is either resolved with the resulting data or rejected with an error.

Parameters

params

Partial<MutationOptions<Data<D>, Variables<D, V>>>

All named arguments to mutate default to the element's corresponding instance property. So you can call element.mutate() without arguments and it will call using element.mutation, element.variables, etc. You can likewise override instance properties per-call by passing them in, e.g.

await element.mutate({
  fetchPolicy: 'network-only'
  variables: {
    ...element.variables,
    name: 'overridden',
  },
});
Property Type Description
awaitRefetchQueries boolean See awaitRefetchQueries
context Record<string, unknown> See context
errorPolicy ErrorPolicy See errorPolicy
fetchPolicy FetchPolicy See fetchPolicy
mutation DocumentNode See mutation
optimisticResponse OptimisticResponseType<D, V> See optimisticResponse
refetchQueries RefetchQueriesType<D, V> See refetchQueries
update MutationUpdaterFn<Data<D>, Variables<D, V>> See updater
variables Variables<D, V> See variables

Returns

Promise<FetchResult<Data<D>>>
Property Type Description
data Data<D, V> The result of a successful execution of the mutation
errors readonly GraphQLError[] included when any errors occurred as a non-empty array
extensions boolean Reserved for adding non-standard properties
context Record<string, unknown> See context

Events

Name Type Description
apollo-mutation-result
CustomEvent<FetchResult<Data<D>>>

The mutation resolved

apollo-error
CustomEvent<ApolloError>

The mutation rejected

apollo-element-connected
ApolloElementEvent

The element connected to the DOM

apollo-element-disconnected
ApolloElementEvent

The element disconnected from the DOM

Private API

Private Methods

protected

documentChanged

inherited from ApolloElementElement

Lifecycle callback that reacts to changes in the GraphQL document

Parameters

document

ComponentDocument<D, V> | null

Returns

void
protected

variablesChanged

inherited from ApolloElementElement

Lifecycle callback that reacts to changes in the operation variables

Parameters

variables

Variables<D, V> | null

Returns

void

Exports

import {
  CustomElement,
  ControllerHost,
  ApolloElementElement,
  ApolloMutationElement,
  ApolloQueryElement,
  ApolloSubscriptionElement
} from '@apollo-elements/core/types';