Components
Deprecated React Apollo render prop component API
Note: Official support for React Apollo render prop components ended in March 2020. This library is still included in the
@apollo/client
package, but it no longer receives feature updates or bug fixes.
Installation
The render prop library is included in the core @apollo/client
package:
1npm install @apollo/client
You then import the library's symbols from @apollo/client/react/components
.
Query
Props
The Query
component accepts the following props. query
is required.
ApolloClient<any>
The instance of ApolloClient
to use to execute the query.
By default, the instance that's passed down via context is used, but you can provide a different instance here.
ErrorPolicy
Specifies how the query 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 query result includes error details but not partial results.
(data: TData) => void
A callback function that's called when your query successfully completes with zero errors (or if errorPolicy
is ignore
and partial data is returned).
This function is passed the query's result data
.
(error: ApolloError) => void
A callback function that's called when the query encounters one or more errors (unless errorPolicy
is ignore
).
This function is passed an ApolloError
object that contains either a networkError
object or a graphQLErrors
array, depending on the error(s) that occurred.
boolean
If true, the query is not executed.
The default value is false
.
TVariables
An object containing all of the GraphQL variables your query requires to execute.
Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value.
DefaultContext
If you're using Apollo Link , this object is the initial value of the context
object that's passed along your link chain.
If true
, the in-progress query's associated component re-renders whenever the network status changes or a network error occurs.
The default value is false
.
number
Specifies the interval (in milliseconds) at which the query polls for updated results.
The default value is 0
(no polling).
() => boolean
A callback function that's called whenever a refetch attempt occurs while polling. If the function returns true
, the refetch is skipped and not reattempted until the next poll interval.
boolean
Pass false
to skip executing the query during server-side rendering .
WatchQueryFetchPolicy
Specifies how the query interacts with the Apollo Client cache during execution (for example, whether it checks the cache for results before sending a request to the server).
For details, see Setting a fetch policy .
The default value is cache-first
.
WatchQueryFetchPolicy
Defaults to the initial value of options.fetchPolicy, but can be explicitly configured to specify the WatchQueryFetchPolicy to revert back to whenever variables change (unless nextFetchPolicy intervenes).
WatchQueryFetchPolicy | ((this: WatchQueryOptions<TVariables, TData>, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext<TData, TVariables>) => WatchQueryFetchPolicy)
Specifies the FetchPolicy
to be used after this query has completed.
RefetchWritePolicy
Specifies whether a NetworkStatus.refetch
operation should merge incoming field data with existing data, or overwrite the existing data. Overwriting is probably preferable, but merging is currently the default behavior, for backwards compatibility with Apollo Client 3.x.
boolean
If true
, the query can return partial results from the cache if the cache doesn't contain results for all queried fields.
The default value is false
.
boolean
⚠️ Deprecated
Using
canonizeResults
can result in memory leaks so we generally do not recommend using this option anymore. A future version of Apollo Client will contain a similar feature without the risk of memory leaks.
Whether to canonize cache results before returning them. Canonization takes some extra time, but it speeds up future deep equality comparisons. Defaults to false.
boolean
⚠️ Deprecated
Setting this option is unnecessary in Apollo Client 3, thanks to a more consistent application of fetch policies. It might be removed in a future release.
If true
, causes a query refetch if the query result is detected as partial.
The default value is false
.
Render prop function
The render prop function that you pass to the children
prop of Query
is called with an object (QueryResult
) that has the following properties. This object contains your query result, plus some helpful functions for refetching, dynamic polling, and pagination.
TData | undefined
An object containing the result of your GraphQL query after it completes.
This value might be undefined
if a query results in one or more errors (depending on the query's errorPolicy
).
ApolloError
If the query produces one or more errors, this object contains either an array of graphQLErrors
or a single networkError
. Otherwise, this value is undefined
.
For more information, see Handling operation errors .
TData
An object containing the result from the most recent previous execution of this query.
This value is undefined
if this is the query's first execution.
TVariables | undefined
An object containing the variables that were provided for the query.
boolean
If true
, the associated lazy query has been executed.
This field is only present on the result object returned by useLazyQuery
.
ApolloClient<any>
The instance of Apollo Client that executed the query. Can be useful for manually executing followup queries or writing data to the cache.
boolean
If true
, the query is still in flight and results have not yet been returned.
NetworkStatus
A number indicating the current network state of the query's associated request. See possible values.
Used in conjunction with the notifyOnNetworkStatusChange
option.
<TFetchData = TData, TFetchVars extends OperationVariables = TVariables>(fetchMoreOptions: FetchMoreQueryOptions<TFetchVars, TFetchData> & {
updateQuery?: (previousQueryResult: TData, options: {
fetchMoreResult: TFetchData;
variables: TFetchVars;
}) => TData;
}) => Promise<ApolloQueryResult<TFetchData>>
A function that helps you fetch the next set of results for a paginated list field .
(variables?: Partial<TVariables>) => Promise<ApolloQueryResult<TData>>
A function that enables you to re-execute the query, optionally passing in new variables
.
To guarantee that the refetch performs a network request, its fetchPolicy
is set to network-only
(unless the original query's fetchPolicy
is no-cache
or cache-and-network
, which also guarantee a network request).
See also Refetching .
(pollInterval: number) => void
A function that instructs the query to begin re-executing at a specified interval (in milliseconds).
() => void
A function that instructs the query to stop polling after a previous call to startPolling
.
<TSubscriptionData = TData, TSubscriptionVariables extends OperationVariables = TVariables>(options: SubscribeToMoreOptions<TData, TSubscriptionVariables, TSubscriptionData>) => () => void
A function that enables you to execute a subscription , usually to subscribe to specific fields that were included in the query.
This function returns another function that you can call to terminate the subscription.
<TVars extends OperationVariables = TVariables>(mapFn: (previousQueryResult: TData, options: Pick<WatchQueryOptions<TVars, TData>, "variables">) => TData) => void
A function that enables you to update the query's cached result without executing a followup GraphQL operation.
See using updateQuery and updateFragment for additional information.
ObservableQuery<TData, TVariables>
A reference to the internal ObservableQuery
used by the hook.
ReadonlyArray<GraphQLFormattedError>
⚠️ Deprecated
This property will be removed in a future version of Apollo Client. Please use
error.graphQLErrors
instead.
Mutation
The Mutation component accepts the following props. Only mutation
is required.
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).
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.
boolean
If true
, the mutation's data
property is not updated with the mutation's result.
The default value is false
.
DocumentNode | TypedDocumentNode<TData, TVariables>
A GraphQL document, often created with gql
from the graphql-tag
package, that contains a single mutation inside of it.
(data: TData, clientOptions?: BaseMutationOptions) => void
A callback function that's called when your mutation successfully completes with zero errors (or if errorPolicy
is ignore
and partial data is returned).
This function is passed the mutation's result data
and any options passed to the mutation.
(error: ApolloError, clientOptions?: BaseMutationOptions) => void
A callback function that's called when the mutation encounters one or more errors (unless errorPolicy
is ignore
).
This function is passed an ApolloError
object that contains either a networkError
object or a graphQLErrors
array, depending on the error(s) that occurred, as well as any options passed the mutation.
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.
((result: FetchResult<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 anyvariables
A string indicating the operation name of the query to refetch
TVariables
An object containing all of the GraphQL variables your mutation requires to execute.
Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value.
ApolloClient<object>
The instance of ApolloClient
to use to execute the mutation.
By default, the instance that's passed down via context is used, but you can provide a different instance here.
TContext
If you're using Apollo Link , this object is the initial value of the context
object that's passed along your link chain.
If true
, the in-progress mutation's associated component re-renders whenever the network status changes or a network error occurs.
The default value is false
.
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
.
TData | ((vars: TVariables, { IGNORE }: {
IGNORE: IgnoreModifier;
}) => 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 .
MutationUpdaterFunction<TData, TVariables, TContext, TCache>
A function used to update the Apollo Client cache after the mutation completes.
For more information, see Updating the cache after a mutation .
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.
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.
Render prop function
The render prop function that you pass to the children
prop of Mutation
is called with the mutate
function and an object with the mutation result. The mutate
function is how you trigger the mutation from your UI. The object contains your mutation result, plus loading and error state.
boolean
If true
, the mutation's mutate function has been called.
ApolloClient<object>
The instance of Apollo Client that executed the mutation.
Can be useful for manually executing followup operations or writing data to the cache.
TData | null
The data returned from your mutation. Can be undefined
if ignoreResults
is true
.
ApolloError
If the mutation produces one or more errors, this object contains either an array of graphQLErrors
or a single networkError
. Otherwise, this value is undefined
.
For more information, see Handling operation errors .
boolean
If true
, the mutation is currently in flight.
() => void
A function that you can call to reset the mutation's result to its initial, uncalled state.
Subscription
Props
The Subscription component accepts the following props. Only subscription
is required.
null | ((result: SubscriptionResult<TData>) => ReactTypes.JSX.Element | null)
ApolloClient<object>
An ApolloClient
instance. By default useSubscription
/ Subscription
uses the client passed down via context, but a different client can be passed in.
DefaultContext
Shared context between your component and your network interface (Apollo Link).
ErrorPolicy
Specifies the ErrorPolicy
to be used for this operation
Record<string, any>
Shared context between your component and your network interface (Apollo Link).
FetchPolicy
How you want your component to interact with the Apollo cache. For details, see Setting a fetch policy .
boolean
If true
, the hook will not cause the component to rerender. This is useful when you want to control the rendering of your component yourself with logic in the onData
and onError
callbacks.
Changing this to true
when the hook already has data
will reset the data
to undefined
.
onComplete
(optional) Since 3.7.0
() => void
Allows the registration of a callback function that will be triggered each time the useSubscription
Hook / Subscription
component completes the subscription.
onData
(optional) Since 3.7.0
(options: OnDataOptions<TData>) => any
Allows the registration of a callback function that will be triggered each time the useSubscription
Hook / Subscription
component receives data. The callback options
object param consists of the current Apollo Client instance in client
, and the received subscription data in data
.
onError
(optional) Since 3.7.0
(error: ApolloError) => void
Allows the registration of a callback function that will be triggered each time the useSubscription
Hook / Subscription
component receives an error.
boolean | ((options: BaseSubscriptionOptions<TData, TVariables>) => boolean)
Determines if your subscription should be unsubscribed and subscribed again when an input to the hook (such as subscription
or variables
) changes.
boolean
Determines if the current subscription should be skipped. Useful if, for example, variables depend on previous queries and are not ready yet.
DocumentNode | TypedDocumentNode<TData, TVariables>
A GraphQL document, often created with gql
from the graphql-tag
package, that contains a single subscription inside of it.
TVariables
An object containing all of the variables your subscription needs to execute
() => void
⚠️ Deprecated
Use
onComplete
instead
Allows the registration of a callback function that will be triggered when the useSubscription
Hook / Subscription
component completes the subscription.
(options: OnSubscriptionDataOptions<TData>) => any
⚠️ Deprecated
Use
onData
instead
Allows the registration of a callback function that will be triggered each time the useSubscription
Hook / Subscription
component receives data. The callback options
object param consists of the current Apollo Client instance in client
, and the received subscription data in subscriptionData
.
Render prop function
TData
An object containing the result of your GraphQL subscription. Defaults to an empty object.
ApolloError
A runtime error with graphQLErrors
and networkError
properties
boolean
A boolean that indicates whether any initial data has been returned