GraphQL Summit is back for three days of insights, hands-on learning, and fun to celebrate the GraphQL community. Join us in San Diego Oct 3-5.
Try Apollo Studio

Using the @defer directive in Apollo Client

Fetch slower schema fields asynchronously

⚠️ The @defer directive is currently at the preview stage in Apollo Client, and is available by installing @apollo/client@next. If you have feedback on it, please let us know via GitHub issues.

Beginning with version 3.7.0, Apollo Client Web provides preview support for the @defer directive, which enables your queries to receive data for specific fields asynchronously. This is helpful whenever some fields in a query take much longer to resolve than the others.

For example, let's say we're building a social media application that can quickly fetch a user's basic profile information, but retrieving that user's friends takes longer. If we include all of those fields in a single query, we want to be able to display the profile information as soon as it's available, instead of waiting for the friend fields to resolve.

To achieve this, we can apply the @defer directive to an in-line fragment that contains all slow-resolving fields related to friend data:

query PersonQuery($personId: ID!) {
person(id: $personId) {
# Basic fields (fast)
# Friend fields (slower)
... on User @defer {
friends {

Using with code generation

If you currently use GraphQL Code Generator for your codegen needs, note that it doesn't yet support the use of the @defer directive in the code output.

For reference, refer to this GitHub issue.

Edit on GitHub
Error handling