On this page, you can learn how to use
react-apollo to attach GraphQL query results to your React UI. This guide assumes some familiarity with GraphQL itself. You can read about GraphQL queries themselves in detail at graphql.org.
One of our core values is “it’s just GraphQL”. 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 IDE, 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 using the
gql template literal 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 with a GraphQL query document, two things happen:
- The query is loaded from the Apollo client-side data store, or the server if the data is not in the store
- Our component subscribes to the store, so that it is updated if the data changes as the result of a mutation or some other response from the server
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. So if we were to declare
propTypes they would look like this:
data.currentUser 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 about cache updates.
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.
There are a lot more methods as well, which you can read about in the API docs for queries. As an example, for a query like this:
You could get props 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
Variables and options
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 requires variables, this is the place to pass them in:
Computing from props
Typically, variables to the query will be computed from the
props of the wrapper component. Wherever the component is used in your application, the caller would pass arguments. So
options can be a function that takes the props passed into the component:
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
graphql(CurrentUserForLayout)(Profile);. However, if you need to change the name of a variable, compute the value, or just want to be more explicit about things, the
options function is the place to do it.
There are a lot of other options you can pass in other than just
variables, for example
If you use a function to compute options from props, all of these
options will be automatically recalculated whenever the props change.
Skipping an operation
graphql container API is intentionally fully static, so you can’t dynamically change the query or wrapped component at runtime without generating a new React component. However, sometimes you may want to do some conditional logic to skip a query based on the passed in props. To do this you can use the
For example, you could use this if you want to ignore a query if a user isn’t authenticated:
skip can also be a static property:
skip config completely bypasses the higher-order component, as if it weren’t there at all. This means your child component doesn’t get a
data prop at all, and the
props methods are not called.
Controlling child props
graphql used with a query 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. It’s possible to write your whole app just using these default prop names.
However, if you want to decouple your UI components from Apollo and make them more reusable in different contexts, you may want to modify these default props and wrap them with your own custom objects and functions.
Changing the prop name
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 when one component is using multiple queries via nested
graphql containers, where the
data prop would otherwise be overwritten.
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