On this page, you can learn how to use
react-apollo to attach GraphQL query results to your React UI. You can read about GraphQL queries themselves in detail at graphql.org.
Note that when using
react-apollo, you don’t have to learn anything special about the query syntax, since everything is just standard GraphQL. Anything you can type into the GraphiQL query explorer, you can also put into your
When we are running a basic query we can use the
graphql container in a very simple way. We simply parse our query into a GraphQL document using the
graphql-tag library, and then pass it into the
graphql container as the first argument.
For instance, in GitHunt, we want to display the currently logged-in user in the
When we use
graphql in this simple way with a GraphQL query document,
ApolloClient.watchQuery is used under the hood to execute the query before the results are passed to the child component in a prop called
data. In addition to the
currentUser field selected in the query, the
data prop also includes a field called
loading, a Boolean value indicating if the query is currently being loaded from the server.
data.currentUser sub-prop will change as what the client knows about the current user changes over time. That information is stored in Apollo Client’s global cache, so if some other query fetches new information about the current user, this component will update to remain consistent. You can read more about techniques to bring the cache up to date with the server in the article on the subject.
The structure of the
As seen above,
graphql will pass the result of the query to the wrapped component in a prop called
data. It will also pass through all of the props of the parent container.
For queries, the shape of the
data prop is the following:
...fields: One key for each root field in the query.
loading: This field is
trueif there is currently a query fetch in flight, including after calling
error: An ApolloError object that represents the different possible errors that might happen when running a query.
...QuerySubscription: All of the methods from the Apollo QuerySubscription object, including
fetchMore, and others.
Here’s a complete example. For a query like this:
You would get a prop like:
If you use the
props option to the wrapper to specify custom
props for your child component, this object will be passed to the
props option on the parameter named
If you want to configure the query, you can provide an
options key on the second argument to
graphql, and your options will be passed along to
ApolloClient.watchQuery. If your query takes variables, this is the place to pass them in:
Typically, variables to the query will be configured by the
props of the wrapper component; where ever the component is used in your application, the caller would pass arguments. So
options can be a function that takes the props of the outer component (
ownProps by convention):
graphql will attempt to pick up any missing variables from the query from
ownProps. So in our example above, we could have used the simpler
ProfileWithData = graphql(CurrentUserForLayout)(Profile);. However, if you need to change the name of a variable, or compute the value (or just want to be more explicit about things), the
options function is the place to do it.
You may want to configure the options used by Apollo’s watchQuery using
All of these function-based forms of
options will be recalculated whenever the props change.
Skipping an operation
Sometimes you may want to skip a query based on the available information. To do this you can pass
skip: true as part of the options. This is useful if you want to ignore a query if a user isn’t authenticated:
This can also be represented as an object instead of a method that takes props:
This does not pass
dataor run the
propsmethods if passed. It effectively bypasses the HOC.
Controlling child props
graphql will provide a
data prop to the wrapped component with various information about the state of the query. We’ll also see that mutations provide a callback on the
mutate prop. Thus, it’s possible to write your whole app just using these default prop names.
If you want to decouple your UI components from Apollo and make them more reusable, you may want to modify these default props into your own custom objects and functions.
If you want to change the name of the default
data prop, but keep the exact same shape, you can use
name option to the
graphql container. This is especially useful for nested
graphql containers, where the
data prop would clash between them.
If you want complete control over the props of the child component, use the
props option to map the query
data object into any number of props that will be passed into the child:
This style of usage leads to the greatest decoupling between your presentational component (
Profile) and Apollo.
For more information about all of the options and features supported by React Apollo for GraphQL queries be sure to review the API reference on