Docs
Launch GraphOS Studio

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:

npm 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.

Operation options

client (optional)

ApolloClient<any>

The instance of ApolloClient to use to execute the .

By default, the instance that's passed down via context is used, but you can provide a different instance here.

Specifies how the handles a response that returns both errors and partial results.

For details, see GraphQL error policies.

The default value is none, meaning that the result includes error details but not partial results.

(data: TData) => void

A callback function that's called when your successfully completes with zero errors (or if errorPolicy is ignore and partial data is returned).

This function is passed the 's result data.

(error: ApolloError) => void

A callback function that's called when the 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.

If true, the is not executed.

The default value is false.

An object containing all of the your requires to execute.

Each key in the object corresponds to a name, and that key's value corresponds to the variable value.

Networking options
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 's associated component re-renders whenever the network status changes or a network error occurs.

The default value is false.

Specifies the interval (in milliseconds) at which the polls for updated results.

The default value is 0 (no polling).

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.

Pass false to skip executing the during server-side rendering.

Caching options
WatchQueryFetchPolicy

Specifies how the interacts with the 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 WatchFetchPolicy to revert back to whenever change (unless nextFetchPolicy intervenes).

WatchQueryFetchPolicy | ((this: WatchQueryOptions<TVariables, TData>, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext<TData, TVariables>) => WatchQueryFetchPolicy)

Specifies the FetchPolicy to be used after this has completed.

Specifies whether a NetworkStatus.refetch should merge incoming data with existing data, or overwrite the existing data. Overwriting is probably preferable, but merging is currently the default behavior, for backwards compatibility with 3.x.

If true, the can return partial results from the cache if the cache doesn't contain results for all queried .

The default value is false.

Other

⚠️ Deprecated

Using canonizeResults can result in memory leaks so we generally do not recommend using this option anymore. A future version of 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.

⚠️ Deprecated

Setting this option is unnecessary in 3, thanks to a more consistent application of fetch policies. It might be removed in a future release.

If true, causes a 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 result, plus some helpful functions for refetching, dynamic polling, and pagination.

Operation data
TData | undefined

An object containing the result of your after it completes.

This value might be undefined if a results in one or more errors (depending on the query's errorPolicy).

ApolloError

If the 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.

An object containing the result from the most recent previous execution of this .

This value is undefined if this is the 's first execution.

TVariables | undefined

An object containing the that were provided for the .

Network info
boolean

If true, the associated lazy has been executed.

This is only present on the result object returned by useLazyQuery.

ApolloClient<any>

The instance of that executed the . Can be useful for manually executing followup queries or writing data to the cache.

boolean

If true, the is still in flight and results have not yet been returned.

NetworkStatus

A number indicating the current network state of the 's associated request. See possible values.

Used in conjunction with the notifyOnNetworkStatusChange option.

Helper functions
<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 , optionally passing in new variables.

To guarantee that the refetch performs a network request, its fetchPolicy is set to network-only (unless the original '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 to begin re-executing at a specified interval (in milliseconds).

() => void

A function that instructs the 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 that were included in the .

This function returns another function that you can call to terminate the .

<TVars extends OperationVariables = TVariables>(mapFn: (previousQueryResult: TData, options: Pick<WatchQueryOptions<TVars, TData>, "variables">) => TData) => void

A function that enables you to update the 's cached result without executing a followup .

See using updateQuery and updateFragment for additional information.

Other
ObservableQuery<TData, TVariables>

A reference to the internal ObservableQuery used by the hook.

Mutation

The component accepts the following props. Only mutation is required.

Operation options

If true, makes sure all queries included in refetchQueries are completed before the is considered complete.

The default value is false (queries are refetched asynchronously).

Specifies how the handles a response that returns both errors and partial results.

For details, see GraphQL error policies.

The default value is none, meaning that the result includes error details but not partial results.

If true, the 's data property is not updated with the 's result.

The default value is false.

DocumentNode | TypedDocumentNode<TData, TVariables>

A , often created with gql from the graphql-tag package, that contains a single inside of it.

(data: TData, clientOptions?: BaseMutationOptions) => void

A callback function that's called when your successfully completes with zero errors (or if errorPolicy is ignore and partial data is returned).

This function is passed the 's result data and any options passed to the .

(error: ApolloError, clientOptions?: BaseMutationOptions) => void

A callback function that's called when the 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 .

OnQueryUpdated<any>

Optional callback for intercepting queries whose cache data has been updated by the , as well as any queries specified in the refetchQueries: [...] list passed to client.mutate.

Returning a Promise from onQueryUpdated will cause the final Promise to await the returned Promise. Returning false causes the 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 occurs.

Each array value can be either:

  • An object containing the query to execute, along with any variables

  • A string indicating the of the to refetch

An object containing all of the your requires to execute.

Each key in the object corresponds to a name, and that key's value corresponds to the variable value.

Networking options
ApolloClient<object>

The instance of ApolloClient to use to execute the .

By default, the instance that's passed down via context is used, but you can provide a different instance here.

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 's associated component re-renders whenever the network status changes or a network error occurs.

The default value is false.

Caching options
MutationFetchPolicy

Provide no-cache if the 's result should not be written to the cache.

The default value is network-only (which means the result is written to the cache).

Unlike queries, do not support fetch policies besides network-only and no-cache.

TData | ((vars: TVariables, { IGNORE }: { IGNORE: IgnoreModifier; }) => TData)

By providing either an object or a callback function that, when invoked after a , allows you to return optimistic data and optionally skip updates via the IGNORE sentinel object, caches this temporary (and potentially incorrect) response until the completes, enabling more responsive UI updates.

For more information, see Optimistic mutation results.

MutationUpdaterFunction<TData, TVariables, TContext, TCache>

A function used to update the cache after the completes.

For more information, see Updating the cache after a mutation.

Other

To avoid retaining sensitive information from root , v3.4+ automatically clears any ROOT_MUTATION from the cache after each finishes. If you need this information to remain in the cache, you can prevent the removal by passing keepRootFields: true to the . ROOT_MUTATION result data are also passed to the 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 names to 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 result. The mutate function is how you trigger the from your UI. The object contains your mutation result, plus loading and error state.

Other
boolean

If true, the 's mutate function has been called.

ApolloClient<object>

The instance of that executed the .

Can be useful for manually executing followup or writing data to the cache.

TData | null

The data returned from your . Can be undefined if ignoreResults is true.

ApolloError

If the 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 is currently in flight.

() => void

A function that you can call to reset the 's result to its initial, uncalled state.

Subscription

Props

The component accepts the following props. Only subscription is required.

Other
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 ().

How you want your component to interact with the Apollo cache. For details, see Setting a fetch policy.

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 .

(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 instance in client, and the received data in data.

(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 should be unsubscribed and subscribed again when an input to the hook (such as subscription or variables) changes.

Determines if the current should be skipped. Useful if, for example, depend on previous queries and are not ready yet.

DocumentNode | TypedDocumentNode<TData, TVariables>

A , often created with gql from the graphql-tag package, that contains a single inside of it.

An object containing all of the your needs to execute

⚠️ Deprecated

Use onComplete instead

Allows the registration of a callback function that will be triggered when the useSubscription Hook / Subscription component completes the .

(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 instance in client, and the received data in subscriptionData.

Render prop function

Other

An object containing the result of your . 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

Previous
SSR
Next
HOC (deprecated)
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company