@apollo/react-components
API reference
Installation
npm install @apollo/react-components
Query
Props
The Query component accepts the following props. query is required.
| Option | Type | Description |
|---|---|---|
query | DocumentNode | A GraphQL query document parsed into an AST by graphql-tag. Optional for the useQuery Hook since the query can be passed in as the first parameter to the Hook. Required for the Query component. |
variables | { [key: string]: any } | An object containing all of the variables your query needs to execute |
pollInterval | number | Specifies the interval in ms at which you want your component to poll for data. Defaults to 0 (no polling). |
notifyOnNetworkStatusChange | boolean | Whether updates to the network status or network error should re-render your component. Defaults to false. |
fetchPolicy | FetchPolicy | How you want your component to interact with the Apollo cache. Defaults to "cache-first". |
errorPolicy | ErrorPolicy | How you want your component to handle network and GraphQL errors. Defaults to "none", which means we treat GraphQL errors as runtime errors. |
ssr | boolean | Pass in false to skip your query during server-side rendering. |
displayName | string | The name of your component to be displayed in React DevTools. Defaults to 'Query'. |
skip | boolean | If skip is true, the query will be skipped entirely. Not available with useLazyQuery. |
onCompleted | (data: TData | {}) => void | A callback executed once your query successfully completes. |
onError | (error: ApolloError) => void | A callback executed in the event of an error. |
context | Record<string, any> | Shared context between your component and your network interface (Apollo Link). Useful for setting headers from props or sending information to the request function of Apollo Boost. |
partialRefetch | boolean | If true, perform a query refetch if the query result is marked as being partial, and the returned data is reset to an empty Object by the Apollo Client QueryManager (due to a cache miss). The default value is false for backwards-compatibility's sake, but should be changed to true for most use-cases. |
client | ApolloClient | An ApolloClient instance. By default useQuery / Query uses the client passed down via context, but a different client can be passed in. |
returnPartialData | boolean | Opt into receiving partial results from the cache for queries that are not fully satisfied by the cache. false by default. |
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.
| Property | Type | Description |
|---|---|---|
data | TData | An object containing the result of your GraphQL query. Defaults to undefined. |
loading | boolean | A boolean that indicates whether the request is in flight |
error | ApolloError | A runtime error with graphQLErrors and networkError properties |
variables | { [key: string]: any } | An object containing the variables the query was called with |
networkStatus | NetworkStatus | A number from 1-8 corresponding to the detailed state of your network request. Includes information about refetching and polling status. Used in conjunction with the notifyOnNetworkStatusChange prop. |
refetch | (variables?: TVariables) => Promise<ApolloQueryResult> | A function that allows you to refetch the query and optionally pass in new variables |
fetchMore | ({ query?: DocumentNode, variables?: TVariables, updateQuery: Function}) => Promise<ApolloQueryResult> | A function that enables pagination for your query |
startPolling | (interval: number) => void | This function sets up an interval in ms and fetches the query each time the specified interval passes. |
stopPolling | () => void | This function stops the query from polling. |
subscribeToMore | (options: { document: DocumentNode, variables?: TVariables, updateQuery?: Function, onError?: Function}) => () => void | A function that sets up a subscription. subscribeToMore returns a function that you can use to unsubscribe. |
updateQuery | (previousResult: TData, options: { variables: TVariables }) => TData | A function that allows you to update the query's result in the cache outside the context of a fetch, mutation, or subscription |
client | ApolloClient | Your ApolloClient instance. Useful for manually firing queries or writing data to the cache. |
called | boolean | A boolean indicating if the query function has been called, used by useLazyQuery (not set for useQuery / Query). |
Mutation
The Mutation component accepts the following props. Only mutation is required.
| Option | Type | Description |
|---|---|---|
mutation | DocumentNode | A GraphQL mutation document parsed into an AST by graphql-tag. Optional for the useMutation Hook since the mutation can be passed in as the first parameter to the Hook. Required for the Mutation component. |
variables | { [key: string]: any } | An object containing all of the variables your mutation needs to execute |
update | (cache: DataProxy, mutationResult: FetchResult) | A function used to update the cache after a mutation occurs |
ignoreResults | boolean | If true, the returned data property will not update with the mutation result. |
optimisticResponse | Object | Provide a mutation response before the result comes back from the server |
refetchQueries | Array<string|{ query: DocumentNode, variables?: TVariables}> | ((mutationResult: FetchResult) => Array<string|{ query: DocumentNode, variables?: TVariables}>) | An array or function that allows you to specify which queries you want to refetch after a mutation has occurred. Array values can either be queries (with optional variables) or just the string names of queries to be refeteched. |
awaitRefetchQueries | boolean | 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. |
onCompleted | (data: TData) => void | A callback executed once your mutation successfully completes |
onError | (error: ApolloError) => void | A callback executed in the event of an error. |
context | Record<string, any> | Shared context between your component and your network interface (Apollo Link). Useful for setting headers from props or sending information to the request function of Apollo Boost. |
client | ApolloClient | An ApolloClient instance. By default useMutation / Mutation uses the client passed down via context, but a different client can be passed in. |
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.
Mutate function:
| Property | Type | Description |
|---|---|---|
mutate | (options?: MutationOptions) => Promise<FetchResult> | A function to trigger a mutation from your UI. You can optionally pass variables, optimisticResponse, refetchQueries, and update in as options, which will override options/props passed to useMutation / Mutation. The function returns a promise that fulfills with your mutation result. |
Mutation result:
| Property | Type | Description |
|---|---|---|
data | TData | The data returned from your mutation. It can be undefined if ignoreResults is true. |
loading | boolean | A boolean indicating whether your mutation is in flight |
error | ApolloError | Any errors returned from the mutation |
called | boolean | A boolean indicating if the mutate function has been called |
client | ApolloClient | Your ApolloClient instance. Useful for invoking cache methods outside the context of the update function, such as client.writeData and client.readQuery. |
Subscription
Props
The Subscription component accepts the following props. Only subscription is required.
| Option | Type | Description |
|---|---|---|
subscription | DocumentNode | A GraphQL subscription document parsed into an AST by graphql-tag. Optional for the useSubscription Hook since the subscription can be passed in as the first parameter to the Hook. Required for the Subscription component. |
variables | { [key: string]: any } | An object containing all of the variables your subscription needs to execute |
shouldResubscribe | boolean | Determines if your subscription should be unsubscribed and subscribed again |
skip | boolean | If skip is true, the subscription will be skipped entirely |
onSubscriptionData | (options: OnSubscriptionDataOptions<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 subscriptionData. |
fetchPolicy | FetchPolicy | How you want your component to interact with the Apollo cache. Defaults to "cache-first". |
client | ApolloClient | An ApolloClient instance. By default useSubscription / Subscription uses the client passed down via context, but a different client can be passed in. |
Render prop function
The render prop function that you pass to the children prop of Subscription is called with an object that has the following properties.
| Property | Type | Description |
|---|---|---|
data | TData | An object containing the result of your GraphQL subscription. Defaults to an empty object. |
loading | boolean | A boolean that indicates whether any initial data has been returned |
error | ApolloError | A runtime error with graphQLErrors and networkError properties |
ApolloProvider
The ApolloProvider component leverages React's Context API to make a configured Apollo Client instance available throughout a React component tree. This component can be imported directly from the @apollo/react-common package where it lives, or from one of the @apollo/react-hooks, @apollo/react-components, and @apollo/react-hoc packages.
import { ApolloProvider } from '@apollo/react-hooks';
Props
| Option | Type | Description |
|---|---|---|
client | ApolloClient<TCache> | An ApolloClient instance. |
Example
ReactDOM.render(<ApolloProvider client={client}><MyRootComponent /></ApolloProvider>,document.getElementById('root'),);