• Public
  • Public/Protected
  • All

Module @apollo-elements/components


Published on npm Published on webcomponents.org ISC License Release

🚀 Web component helpers for Apollo GraphQL 🌑

🦅 The element has registered 👨‍🚀



Providing a client to a tree of Nodes

<apollo-client id="client-a">

Nesting separate clients

<apollo-client id="client-a">
    <!-- This element queries from client-a's endpoint -->
  <apollo-client id="client-b">
      <!-- This element queries from client-b's endpoint -->


Property Modifiers Type Description
client ApolloClient<NormalizedCacheObject> Reference to the ApolloClient instance.
instances readonly Set<ApolloElement> Set of elements subscribed to changes on this element's client


Simple Mutation component that takes a button or link-wrapped button as it's trigger. When loading, it disables the button. On error, it toasts a snackbar with the error message. You can pass a variables object property, or if all your variables properties are strings, you can use the element's data attributes

Mixins: dedupeMixin, ApolloMutationMixinImpl, ApolloElementMixinImplementation


Using data attributes

<apollo-mutation data-type="Type" data-action="ACTION">
  <mwc-button slot="trigger">OK</mwc-button>

Will mutate with the following as variables:

  "type": "Type",
  "action": "ACTION"

Using data attributes and variables

<apollo-mutation data-type="Quote" data-action="FLUB">
  <mwc-button slot="trigger">OK</mwc-button>
  <mwc-textfield slot="variable"
  <textarea slot="variable"
      value="That's one small step..."></mwc-textfield>

Will mutate with the following as variables:

  "name": "Neil",
  "comment": "That's one small step...",
  "type": "Quote",
  "action": "FLUB"

Using data attributes and variables with input property

<apollo-mutation data-type="Type" data-action="ACTION" input-key="actionInput">
  <mwc-button slot="trigger">OK</mwc-button>
  <mwc-textfield slot="variable"

Will mutate with the following as variables:

  "actionInput": {
    "comment": "Hey!",
    "type": "Type",
    "action": "ACTION"

Using DOM properties

    .variables="${{ type: "Type", action: "ACTION" }}">
  <mwc-button slot="trigger">OK</mwc-button>

Will mutate with the following as variables:

  "type": "Type",
  "action": "ACTION"


Property Attribute Type Default Description
awaitRefetchQueries 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.
called called boolean false Whether the mutation has been fired
client ApolloClient<NormalizedCacheObject> "__APOLLO_CLIENT__" The Apollo Client instance.
context Record<string, unknown> | undefined Context to be passed to link execution chain.
data TData null Latest mutation data.
document DocumentNode GraphQL operation document i.e. query, subscription, or mutation.
Must be a parsed GraphQL DocumentNode, so use graphql-tag.
If unset, the element can derive the document from the first
light-DOM <script type="application/graphql"> child.
error Error | ApolloError null Latest error
errorPolicy "none" | "ignore" | "all" | undefined Specifies the ErrorPolicy to be used for this mutation.
errors readonly GraphQLError[] null Latest errors
fetchPolicy "no-cache" | undefined Specifies the FetchPolicy to be used for this mutation.
ignoreResults boolean false If true, the returned data property will not update with the mutation result.
inputKey input-key string "" When set, variable data attributes will be packed into an
object property with the name of this property
loading boolean false Whether a request is in flight.
mostRecentMutationId number 0 The ID number of the most recent mutation since the element was instantiated.
mutation DocumentNode The mutation.
optimisticResponse TData | ((vars: TVariables) => TData) | undefined An object that represents the result of this mutation that
will be optimistically stored before the server has actually returned a

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
refetchQueries refetch-queries RefetchQueryDescription | ((result: FetchResult<{ [key: string]: any; }, Record<string, any>, Record<string, any>>) => RefetchQueryDescription) | undefined null As an attribute, can be a string of comma-separated query names
html<br /><mutation-element refetch-queries="QueryA, QueryB,QueryC"></mutation-element><br />
As a property, you can pass any legal refetchQueries value.
variables Variables null An object that maps from the name of a variable as used in the mutation GraphQL document to that variable's value.


Method Type Description
adoptedCallback ((): void) | undefined Called when the element is adopted to a document.
mutate (params?: Partial<MutationOptions<TData, TVariables>> | undefined): Promise<FetchResult<TData, Record<string, any>, Record<string, any>>> 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.
onCompleted (data: Data): void Callback for when a mutation is completed.
onError (error: ApolloError): void Callback for when an error occurs in mutation.
resolveURL ((data: Data): string | Promise<string>) | undefined Define this function to determine the URL to navigate to after a mutation.
Function can be synchronous or async.
If this function is not defined, will navigate to the href property of the link trigger.

data: mutation data
updater ((cache: ApolloCache<TData>, mutationResult: FetchResult<TData, Record<string, any>, Record<string, any>>): void) | undefined 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.


Event Description
apollo-element-connected when the element connects to the dom
apollo-element-disconnected when the element disconnects from the dom
mutation-completed When the mutation resolves. detail is { data: Data, element: this }
mutation-error When the mutation is rejected. detail is { error: ApolloError, element: this }
will-mutate When the element is about to mutate. Useful for setting variables. Prevent default to prevent mutation. Detail is { element: this }
will-navigate When the mutation resolves and the element is about to navigate. cancel the event to handle navigation yourself e.g. using a client-side router. . detail is { data: Data, element: this }


Name Description
trigger the triggering element (e.g. button or anchor)
variable an input-like element with a data-variable attribute. it's value property will be queried to get the value for the corresponding variable